test: adds setup and teardown

.github/workflows/compare-benchmark.yml

@@ -62,7 +62,7 @@ jobs:
       - name: Install and cache yarn
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'yarn'
 
       - name: Install Aztec CLI

.github/workflows/lint.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install and cache yarn
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'yarn'
 
       - name: Cache node_modules
@@ -48,18 +48,25 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Detect Aztec version
+        id: aztec-version
+        run: |
+          AZTEC_VERSION=$(node -p "require('./package.json').config.aztecVersion")
+          echo "version=$AZTEC_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Aztec version is ${{ steps.aztec-version.outputs.version }}" 
+
       - name: Install Aztec CLI
         run: |
           curl -s https://install.aztec.network > tmp.sh
-          bash tmp.sh <<< yes "yes"
+          VERSION=${{ steps.aztec-version.outputs.version }} bash tmp.sh <<< yes "yes"
 
       - name: Update path
         run: echo "/home/runner/.aztec/bin" >> $GITHUB_PATH
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'yarn'
 
       - name: Install dependencies

.github/workflows/tests.yml

@@ -12,19 +12,16 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 60
 
-    env:
-      AZTEC_VERSION: 0.87.2
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+      steps:
+        - name: Checkout repository
+          uses: actions/checkout@v4
+          with:
+            fetch-depth: 0
 
       - name: Install and cache yarn
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'yarn'
 
       - name: Cache node_modules
@@ -38,20 +35,21 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
-      - name: Set up Docker
-        uses: docker/setup-buildx-action@v3    
+      - name: Detect Aztec version
+        id: aztec-version
+        run: |
+          AZTEC_VERSION=$(node -p "require('./package.json').config.aztecVersion")
+          echo "version=$AZTEC_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Aztec version is ${{ steps.aztec-version.outputs.version }}" 
 
       - name: Install Aztec CLI
         run: |
           curl -s https://install.aztec.network > tmp.sh
-          VERSION=$AZTEC_VERSION bash tmp.sh <<< yes "yes"
+          VERSION=${{ steps.aztec-version.outputs.version }} bash tmp.sh <<< yes "yes"
 
       - name: Update path
         run: echo "/home/runner/.aztec/bin" >> $GITHUB_PATH
 
-      - name: Start sandbox
-        run: aztec start --sandbox &
-
       - name: Cache Noir compilation artifacts
         id: cache-noir
         uses: actions/cache@v4
@@ -69,10 +67,6 @@ jobs:
         if: steps.cache-noir.outputs.cache-hit != 'true'
         run: script -e -c "aztec codegen target --outdir src/artifacts"
 
-      - name: Start PXE
-        run: |
-          aztec start --port 8081 --pxe --pxe.nodeUrl=http://localhost:8080/ --pxe.proverEnabled false &
-
       - name: Run nr tests
         run: yarn test:nr
 

README.md

@@ -18,7 +18,7 @@
   <dd>Complete TypeScript setup with generated contract bindings and utilities for interacting with Aztec sandbox.</dd>
 
   <dt>Comprehensive testing</dt>
-  <dd>Noir unit tests for contract logic and TypeScript integration tests using Jest with ESM support.</dd>
+  <dd>Noir unit tests for contract logic and TypeScript integration tests using Jest with ESM support. Tests automatically start and manage the Aztec sandbox - no manual setup required.</dd>
 
   <dt>Automated benchmarking</dt>
   <dd>GitHub Actions workflow that automatically benchmarks your contracts on every PR, comparing Gates, DA Gas and L2 Gas against the base branch.</dd>
@@ -49,10 +49,21 @@ This runs:
 ## Running tests
 
 ### Prerequisites
-Before running tests, ensure the Aztec sandbox is running:
+The tests **automatically start and manage the Aztec sandbox** for you. 
+
+**Option 1: Automatic**
+Just run the tests and the sandbox will be handled automatically:
+
+```bash
+yarn test  # Sandbox starts automatically and stops when tests complete
+```
+
+**Option 2: Manual Control** 
+If you prefer to manage the sandbox yourself (e.g., for debugging or multiple test runs):
 
 ```bash
-aztec start --sandbox
+aztec start --sandbox  # Start manually in separate terminal
+yarn test              # Run tests against existing sandbox
 ```
 
 The sandbox runs on `http://localhost:8080` by default.
@@ -96,12 +107,15 @@ Every pull request automatically:
 
 ### Running benchmarks locally
 
+Benchmarks also benefit from automatic sandbox management:
+
 ```bash
-# Ensure sandbox is running
-aztec start --sandbox
+# Option 1: Automatic sandbox management (recommended)
+yarn benchmark  # Sandbox starts automatically
 
-# Run benchmarks
-yarn benchmark
+# Option 2: Manual sandbox control
+aztec start --sandbox  # Start manually in separate terminal
+yarn benchmark          # Run against existing sandbox
 ```
 
 Benchmark results are saved to `benchmarks/` directory.
@@ -169,7 +183,7 @@ The `increment()` function is private but enqueues a public `increment_internal(
 1. **Modify Noir contracts** in `src/nr/`
 2. **Run `yarn ccc`** to rebuild and regenerate TypeScript artifacts
 3. **Write tests** in `src/ts/` using generated artifacts
-4. **Run tests** with `yarn test`
+4. **Run tests** with `yarn test` (sandbox starts automatically)
 5. **Format code** with `yarn lint:prettier`
 6. **Create PR** and review automated benchmark results
 

jest.integration.config.json

@@ -8,5 +8,7 @@
   },
   "testRegex": "./src/.*\\.test\\.ts$",
   "rootDir": "./src",
-  "testTimeout": 30000
+  "testTimeout": 30000,
+  "globalSetup": "<rootDir>/../jest.setup.js",
+  "globalTeardown": "<rootDir>/../jest.teardown.js"
 }

jest.setup.js

@@ -0,0 +1,27 @@
+import { checkAztecVersion } from "./scripts/check-aztec-version.js";
+import { startSandbox } from "./scripts/start-sandbox.js";
+
+/**
+ * Jest global setup - runs before all tests
+ */
+export default async function setup() {
+  console.log("\n🔧 Setting up Aztec testing environment\n");
+
+  try {
+    // Step 1: Check Aztec CLI version
+    console.log("Step 1: Checking Aztec CLI version compatibility");
+    await checkAztecVersion();
+    console.log("");
+
+    // Step 2: Start sandbox and wait for readiness
+    console.log("Step 2: Starting Aztec sandbox");
+    const sandboxManager = await startSandbox();
+    console.log("");
+
+    // Store sandbox manager globally for teardown
+    globalThis.__AZTEC_SANDBOX_MANAGER__ = sandboxManager;
+  } catch (error) {
+    console.error(`\n❌ Setup failed: ${error.message}`);
+    process.exit(1);
+  }
+}

jest.teardown.js

@@ -0,0 +1,23 @@
+/**
+ * Jest global teardown - runs after all tests
+ */
+export default async function teardown() {
+  console.log("\nLast Step: Cleaning up Aztec testing environment");
+
+  try {
+    // Get the sandbox manager from global storage
+    const sandboxManager = globalThis.__AZTEC_SANDBOX_MANAGER__;
+
+    if (sandboxManager) {
+      await sandboxManager.stop();
+      console.log("✅ Sandbox stopped successfully");
+    } else {
+      console.log("ℹ️  No sandbox manager found, skipping cleanup");
+    }
+
+    console.log("✅ Aztec testing environment cleanup complete\n");
+  } catch (error) {
+    console.error("⚠️  Error during cleanup:", error.message);
+    // Don't exit with error code during cleanup, just log the issue
+  }
+}

scripts/check-aztec-version.js

@@ -0,0 +1,65 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+
+const execAsync = promisify(exec);
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Check if the installed Aztec CLI version matches the expected version in package.json
+ */
+async function checkAztecVersion() {
+  console.log("🔍 Checking Aztec CLI version");
+
+  // Read expected version from package.json
+  const packageJsonPath = join(__dirname, "..", "package.json");
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  const expectedVersion = packageJson.config?.aztecVersion;
+
+  if (!expectedVersion) {
+    throw new Error("❌ No aztecVersion found in package.json config");
+  }
+
+  console.log(`📋 Expected Aztec version: ${expectedVersion}`);
+
+  let installedVersion;
+
+  try {
+    // Check if aztec CLI is installed and get version
+    const { stdout } = await execAsync("aztec --version");
+    installedVersion = stdout.trim();
+
+    console.log("✅ Aztec CLI version check passed");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(
+        `❌ Aztec CLI not found!\n` +
+          `   Please install aztec-up and run: VERSION=${expectedVersion} aztec-up`,
+      );
+    } else if (error.stdout) {
+      // Handle case where command exits with non-zero code (e.g., when sandbox is running)
+      // but version is still available in stdout
+      installedVersion = error.stdout.trim();
+    } else {
+      throw error;
+    }
+  }
+
+  console.log(`🔧 Installed Aztec version: ${installedVersion}`);
+
+  // Compare versions
+  if (installedVersion !== expectedVersion) {
+    throw new Error(
+      `❌ Version mismatch!\n` +
+        `   Expected: ${expectedVersion}\n` +
+        `   Installed: ${installedVersion}\n` +
+        `   Please run: VERSION=${expectedVersion} aztec-up`,
+    );
+  }
+}
+
+export { checkAztecVersion };