refactor: change test setup to use external mock servers without docker

.github/workflows/pr.yml

@@ -22,43 +22,85 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      # TODO: Change to algorandfoundation/algokit-polytest once https://github.com/algorandfoundation/algokit-polytest/pull/18 is merged
       - name: Setup Polytest
-        uses: aorumbayev/algokit-polytest/.github/actions/setup-polytest@main
+        uses: algorandfoundation/algokit-polytest/.github/actions/setup-polytest@main
 
       - name: Validate polytest algod_client tests
         run: npm run polytest:validate-algod
 
-  pull_request:
+  build-and-test:
     needs: setup-polytest
-    uses: makerxstudio/shared-config/.github/workflows/node-ci.yml@main
-    with:
-      node-version: 20.x
-      working-directory: ./
-      run-commit-lint: true
-      run-build: true
-      pre-test-script: |
-        pipx install algokit
-        algokit localnet start
-        npx --yes wait-on tcp:4001 -t 30000
-
-        # Ensure Transaction class has all keys from TransactionParams
-        npm run check-types
-      audit-script: |
-        npm run audit
-  check_docs:
     runs-on: ubuntu-latest
     steps:
-      - name: Clone repository
-        uses: actions/checkout@v3
+      - name: Checkout source code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Commit lint
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
+
+      - name: Lint
+        run: npm run lint --if-present
+
+      - name: Check types
+        run: npm run check-types --if-present
+
+      # Start localnet for integration tests
+      - name: Start LocalNet
+        run: |
+          pipx install algokit
+          algokit localnet start
+          npx --yes wait-on tcp:4001 -t 30000
+
+      # Start mock servers using composite action
+      - name: Start algod mock server
+        uses: algorandfoundation/algokit-polytest/.github/actions/run-mock-server@main
+        with:
+          client: algod
+
+      - name: Start indexer mock server
+        uses: algorandfoundation/algokit-polytest/.github/actions/run-mock-server@main
+        with:
+          client: indexer
+
+      - name: Start kmd mock server
+        uses: algorandfoundation/algokit-polytest/.github/actions/run-mock-server@main
+        with:
+          client: kmd
+
+      - name: Run tests
+        run: npm run test --if-present -- --silent
+
+      - name: Audit
+        run: npm run audit
+
+      - name: Build
+        run: npm run build
+
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
           node-version: 20.x
+
       - name: Check docs are up to date
-        shell: bash
         run: |
           npm ci --ignore-scripts
           npm run generate:code-docs

README.md

@@ -65,13 +65,37 @@ npm run test
 
 ### Mock Server for Client Tests
 
-The `algod_client`, `indexer_client`, and `kmd_client` packages use a Docker-based mock server for deterministic API testing. By default, running tests will automatically start the mock server container.
+The `algod_client`, `indexer_client`, and `kmd_client` packages use a mock server for deterministic API testing against pre-recorded HAR files. The mock server is managed externally (not by the test framework).
 
-To use an external mock server (e.g., for local development):
+**In CI:** Mock servers are automatically started via the [algokit-polytest](https://github.com/algorandfoundation/algokit-polytest) setup.
+
+**Local development:**
+
+1. Clone algokit-polytest and start the mock servers:
+
+```bash
+npm run polytest:start-mock-servers
+```
+
+This starts algod (port 8000), indexer (port 8002), and kmd (port 8001) in the background.
+
+2. Set environment variables and run tests.
+
+| Environment Variable | Description             | Default Port |
+| -------------------- | ----------------------- | ------------ |
+| `MOCK_ALGOD_URL`     | Algod mock server URL   | 8000         |
+| `MOCK_INDEXER_URL`   | Indexer mock server URL | 8002         |
+| `MOCK_KMD_URL`       | KMD mock server URL     | 8001         |
+
+Environment variables can also be set via `.env` file in project root (copy from `.env.template`).
+
+```bash
+# after setting env vars via export or .env file
+npm run test
+```
+
+3. Stop servers when done:
 
 ```bash
-# Set one or more of these environment variables
-export MOCK_ALGOD_URL=http://localhost:18000
-export MOCK_INDEXER_URL=http://localhost:18002
-export MOCK_KMD_URL=http://localhost:18001
+npm run polytest:stop-mock-servers
 ```

package.json

@@ -89,9 +89,10 @@
     "generate:client-algod": "cd oas-generator && uv run oas-generator https://raw.githubusercontent.com/algorandfoundation/algokit-oas-generator/main/specs/algod.oas3.json --output ../packages/algod_client/ --package-name algod_client --description \"TypeScript client for algod interaction.\" --verbose && cd ../packages/algod_client/ && npm run lint:fix && npm run format && cd ..",
     "generate:client-indexer": "cd oas-generator && uv run oas-generator https://raw.githubusercontent.com/algorandfoundation/algokit-oas-generator/main/specs/indexer.oas3.json --output ../packages/indexer_client/ --package-name indexer_client --description \"TypeScript client for indexer interaction.\" --verbose && cd ../packages/indexer_client/ && npm run lint:fix && npm run format && cd ..",
     "generate:client-kmd": "cd oas-generator && uv run oas-generator https://raw.githubusercontent.com/algorandfoundation/algokit-oas-generator/main/specs/kmd.oas3.json --output ../packages/kmd_client/ --package-name kmd_client --description \"TypeScript client for kmd interaction.\" --verbose && cd ../packages/kmd_client/ && npm run lint:fix && npm run format && cd ..",
-    "mock-server:start-algod": "./.polytest_algokit-polytest/resources/mock-server/scripts/start_server.sh algod",
     "polytest:validate-algod": "polytest --config test_configs/algod_client.jsonc --git 'https://github.com/algorandfoundation/algokit-polytest#main' validate -t vitest",
-    "polytest:generate-algod": "polytest --config test_configs/algod_client.jsonc --git 'https://github.com/algorandfoundation/algokit-polytest#main' generate -t vitest"
+    "polytest:generate-algod": "polytest --config test_configs/algod_client.jsonc --git 'https://github.com/algorandfoundation/algokit-polytest#main' generate -t vitest",
+    "polytest:start-mock-servers": ".polytest_algokit-polytest/resources/mock-server/scripts/start_all_servers.sh",
+    "polytest:stop-mock-servers": ".polytest_algokit-polytest/resources/mock-server/scripts/stop_all_servers.sh"
   },
   "overrides": {
     "esbuild": "0.25.0"

packages/testing/src/globalSetup.ts

@@ -6,7 +6,7 @@
 import { config } from 'dotenv'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { startMockServer, stopAllMockServers, type ClientType, type MockServer, MOCK_PORTS } from './mockServer'
+import { getMockServer, type ClientType, type MockServer } from './mockServer'
 
 const currentDir = resolve(fileURLToPath(import.meta.url), '..')
 const projectRoot = resolve(currentDir, '..', '..', '..')
@@ -19,23 +19,18 @@ export function createGlobalSetup(clientType: ClientType) {
   let mockServer: MockServer | null = null
 
   return async function setup(): Promise<() => Promise<void>> {
-    log(`[MockServer] Starting ${clientType} mock server...`)
+    log(`[MockServer] Connecting to ${clientType} mock server...`)
 
     try {
-      mockServer = await startMockServer(clientType)
+      mockServer = await getMockServer(clientType)
       log(`[MockServer] ${clientType} server ready at ${mockServer.baseUrl}`)
 
-      process.env[`MOCK_${clientType.toUpperCase()}_SERVER`] = mockServer.baseUrl
-      process.env[`MOCK_${clientType.toUpperCase()}_PORT`] = String(MOCK_PORTS[clientType].host)
-
       return async () => {
-        log(`[MockServer] Stopping ${clientType} mock server...`)
-        if (mockServer) await mockServer.stop()
-        await stopAllMockServers()
-        log(`[MockServer] ${clientType} server stopped`)
+        log(`[MockServer] Disconnecting from ${clientType} mock server...`)
+        log(`[MockServer] ${clientType} server disconnected`)
       }
     } catch (error) {
-      console.error(`[MockServer] Failed to start ${clientType} server:`, error)
+      console.error(`[MockServer] Failed to connect to ${clientType} server:`, error)
       throw error
     }
   }

packages/testing/src/index.ts

@@ -1,13 +1,11 @@
 export {
   type ClientType,
   type MockServer,
-  MOCK_PORTS,
   EXTERNAL_URL_ENV_VARS,
   DEFAULT_TOKEN,
-  CONTAINER_PREFIX,
-  startMockServer,
-  stopAllMockServers,
-  getStartedContainers,
+  MOCK_PORTS,
+  getMockServer,
+  checkServerHealth,
   TEST_ADDRESS,
   TEST_APP_ID,
   TEST_APP_ID_WITH_BOXES,