zuplo 7.4.4 → 7.4.6

package/docs/articles/ci-cd-azure/local-testing.mdx

@@ -1,6 +1,9 @@
 ---
-title: "Azure Pipelines: Local Testing in CI"
-sidebar_label: Local Testing in CI
+title: "Azure Pipelines: Local testing in CI"
+sidebar_label: Local testing in CI
+description:
+  Start a local Zuplo dev server inside Azure Pipelines, poll it until it
+  answers, run your test suite, and only deploy if every test passes.
 ---
 
 Test against a local Zuplo server before deploying anywhere.
@@ -29,7 +32,16 @@ stages:
           - script: |
               npx zuplo dev &
               DEV_PID=$!
-              sleep 10
+              # Poll until the server answers — never a fixed sleep
+              deadline=$((SECONDS + 60))
+              until curl --fail --silent --output /dev/null http://localhost:9000/health; do
+                if (( SECONDS >= deadline )); then
+                  echo "Local server did not start within 60s" >&2
+                  kill $DEV_PID
+                  exit 1
+                fi
+                sleep 1
+              done
               npx zuplo test --endpoint http://localhost:9000
               kill $DEV_PID
             displayName: "Start local server and run tests"
@@ -54,6 +66,12 @@ stages:
 
 Local tests run first. Only if they pass does deployment proceed.
 
-## Next Steps
+The readiness poll replaces a fixed `sleep`. A sleep is a guess about startup
+time that is wrong in both directions, and it is the most common reason a
+gateway test suite "needs" a retry. The example polls `/health` — add an
+unauthenticated health route if your gateway does not have one. See
+[health checks](../health-checks.mdx).
+
+## Next steps
 
 - Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-bitbucket/local-testing.mdx

@@ -1,6 +1,9 @@
 ---
-title: "Bitbucket Pipelines: Local Testing in CI"
-sidebar_label: Local Testing in CI
+title: "Bitbucket Pipelines: Local testing in CI"
+sidebar_label: Local testing in CI
+description:
+  Start a local Zuplo dev server inside Bitbucket Pipelines, poll it until it
+  answers, run your test suite, and only deploy if every test passes.
 ---
 
 Test against a local Zuplo server before deploying anywhere.
@@ -16,7 +19,16 @@ pipelines:
           script:
             - npm install
             - npx zuplo dev &
-            - sleep 10
+            # Poll until the server answers — never a fixed sleep
+            - |
+              deadline=$((SECONDS + 60))
+              until curl --fail --silent --output /dev/null http://localhost:9000/health; do
+                if (( SECONDS >= deadline )); then
+                  echo "Local server did not start within 60s" >&2
+                  exit 1
+                fi
+                sleep 1
+              done
             - npx zuplo test --endpoint http://localhost:9000
             - kill %1
 
@@ -29,6 +41,12 @@ pipelines:
 
 Local tests run first. Only if they pass does deployment proceed.
 
-## Next Steps
+The readiness poll replaces a fixed `sleep`. A sleep is a guess about startup
+time that is wrong in both directions, and it is the most common reason a
+gateway test suite "needs" a retry. The example polls `/health` — add an
+unauthenticated health route if your gateway does not have one. See
+[health checks](../health-checks.mdx).
+
+## Next steps
 
 - Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-circleci/local-testing.mdx

@@ -1,6 +1,9 @@
 ---
-title: "CircleCI: Local Testing in CI"
-sidebar_label: Local Testing in CI
+title: "CircleCI: Local testing in CI"
+sidebar_label: Local testing in CI
+description:
+  Start a local Zuplo dev server inside CircleCI, poll it until it answers, run
+  your test suite, and only deploy if every test passes.
 ---
 
 Test against a local Zuplo server before deploying anywhere.
@@ -19,7 +22,15 @@ jobs:
           name: Start local server and run tests
           command: |
             npx zuplo dev &
-            sleep 10
+            # Poll until the server answers — never a fixed sleep
+            deadline=$((SECONDS + 60))
+            until curl --fail --silent --output /dev/null http://localhost:9000/health; do
+              if (( SECONDS >= deadline )); then
+                echo "Local server did not start within 60s" >&2
+                exit 1
+              fi
+              sleep 1
+            done
             npx zuplo test --endpoint http://localhost:9000
             kill %1
 
@@ -45,6 +56,12 @@ workflows:
 
 Local tests run first. Only if they pass does deployment proceed.
 
-## Next Steps
+The readiness poll replaces a fixed `sleep`. A sleep is a guess about startup
+time that is wrong in both directions, and it is the most common reason a
+gateway test suite "needs" a retry. The example polls `/health` — add an
+unauthenticated health route if your gateway does not have one. See
+[health checks](../health-checks.mdx).
+
+## Next steps
 
 - Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-github/deploy-and-test.mdx

@@ -1,6 +1,10 @@
 ---
-title: "GitHub Actions: Deploy and Test"
-sidebar_label: Deploy and Test
+title: "GitHub Actions: Deploy and test"
+sidebar_label: Deploy and test
+description:
+  Deploy to Zuplo from a GitHub Actions workflow, capture the deployment URL,
+  and run your test suite against the live environment to validate changes
+  before they reach production.
 ---
 
 Run your test suite against the deployed environment to validate changes before
@@ -54,42 +58,53 @@ jobs:
 
 This workflow:
 
-1. Deploys to Zuplo and captures the deployment URL
-2. Runs your test suite against the live deployment
-3. Fails the workflow if any tests fail
+1. Deploys to Zuplo and captures the deployment URL.
+2. Runs your test suite against the live deployment.
+3. Fails the workflow if any tests fail.
 
 The deploy step passes `--environment` explicitly because this workflow runs on
 both `push` and `pull_request` events. The expression
 `${{ github.head_ref || github.ref_name }}` resolves to the branch name on
 either trigger, so every run for a branch updates the same environment. Without
 it, `pull_request` runs create a second environment named after the PR merge ref
-instead of your branch — see
-[PR Preview Environments](./pr-preview-environments.mdx) for details.
+instead of your branch. For details, see
+[PR preview environments](./pr-preview-environments.mdx).
 
-## Writing Tests
+## Write tests
+
+`describe`, `it`, and `TestHelper` come from `@zuplo/test`, which a Zuplo
+project already has through the `zuplo` package. Assertions use
+[chai](https://www.chaijs.com/api/bdd/), which a new project does **not**
+include. Install it first:
+
+```bash
+npm install --save-dev chai @types/chai
+```
 
 Place test files in the `tests` folder with the `.test.ts` extension:
 
 ```typescript title="tests/api.test.ts"
-import { describe, it } from "@zuplo/test";
+import { describe, it, TestHelper } from "@zuplo/test";
 import { expect } from "chai";
 
 describe("API", () => {
   it("returns 200 for health check", async () => {
-    const response = await fetch(`${ZUPLO_TEST_URL}/health`);
+    const response = await fetch(`${TestHelper.TEST_URL}/health`);
     expect(response.status).to.equal(200);
   });
 
   it("requires authentication", async () => {
-    const response = await fetch(`${ZUPLO_TEST_URL}/protected`);
+    const response = await fetch(`${TestHelper.TEST_URL}/protected`);
     expect(response.status).to.equal(401);
   });
 });
 ```
 
-The `ZUPLO_TEST_URL` variable is automatically set to the `--endpoint` value.
+`TestHelper.TEST_URL` is the value passed to `--endpoint`, so the same files run
+against every environment. For the full setup, see
+[Get started with zuplo test](../testing-getting-started.mdx).
 
-## Next Steps
+## Next steps
 
 - Add [PR preview environments](./pr-preview-environments.mdx) with automatic
   cleanup

package/docs/articles/ci-cd-github/local-testing.mdx

@@ -1,6 +1,9 @@
 ---
-title: "GitHub Actions: Local Testing in CI"
-sidebar_label: Local Testing in CI
+title: "GitHub Actions: Local testing in CI"
+sidebar_label: Local testing in CI
+description:
+  Start a local Zuplo dev server inside a GitHub Actions workflow, poll it until
+  it answers, run your test suite, and only deploy if every test passes.
 ---
 
 Run tests against a local Zuplo development server before deploying anywhere.
@@ -35,9 +38,19 @@ jobs:
           npx zuplo dev &
           DEV_PID=$!
 
-          # Wait for server to be ready
+          # Poll until the server answers, with a hard deadline. Never use a
+          # fixed sleep: it is flaky when the runner is slow and wasted CI
+          # minutes when it is fast.
           echo "Waiting for local server to start..."
-          sleep 10
+          deadline=$((SECONDS + 60))
+          until curl --fail --silent --output /dev/null http://localhost:9000/health; do
+            if (( SECONDS >= deadline )); then
+              echo "Local server did not start within 60s" >&2
+              kill $DEV_PID
+              exit 1
+            fi
+            sleep 1
+          done
 
           # Run tests against local server
           npx zuplo test --endpoint http://localhost:9000
@@ -71,20 +84,27 @@ jobs:
 
 This workflow:
 
-1. Starts a local Zuplo server in the CI environment
-2. Runs your test suite against localhost
-3. Only proceeds to deployment if local tests pass
-4. Deploys to Zuplo (only on pushes to main)
+1. Starts a local Zuplo server in the CI environment.
+2. Polls it until it answers, with a bounded deadline.
+3. Runs your test suite against localhost.
+4. Proceeds to deployment only if local tests pass.
+5. Deploys to Zuplo (only on pushes to main).
 
-## Why Test Locally First?
+The poll replaces a fixed `sleep`. A sleep is a guess about startup time that is
+wrong in both directions, and it is the most common reason a gateway test suite
+"needs" a retry. The example polls `/health` — add an unauthenticated health
+route if your gateway does not have one. See
+[health checks](../health-checks.mdx).
 
-- **Faster feedback** — Local tests run without waiting for deployment
-- **Catch syntax errors** — The local server validates your configuration
-- **Test policies** — Verify authentication, rate limiting, and other policies
-  work correctly
-- **No wasted deployments** — Don't deploy changes that will fail tests
+## Why test locally first
 
-## Combining with Remote Tests
+- **Faster feedback** — local tests run without waiting for deployment.
+- **Catch syntax errors** — the local server validates your configuration.
+- **Test policies** — verify authentication, rate limiting, and other policies
+  work correctly.
+- **No wasted deployments** — don't deploy changes that fail tests.
+
+## Combine with remote tests
 
 For maximum confidence, test both locally and against the deployed environment:
 
@@ -98,7 +118,7 @@ jobs:
     # ... deploy and run tests against live environment ...
 ```
 
-## Next Steps
+## Next steps
 
 - Add [PR preview environments](./pr-preview-environments.mdx) for review
 - Set up [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/ci-cd-gitlab/local-testing.mdx

@@ -1,6 +1,9 @@
 ---
-title: "GitLab CI/CD: Local Testing in CI"
-sidebar_label: Local Testing in CI
+title: "GitLab CI/CD: Local testing in CI"
+sidebar_label: Local testing in CI
+description:
+  Start a local Zuplo dev server inside GitLab CI/CD, poll it until it answers,
+  run your test suite, and only deploy if every test passes.
 ---
 
 Test against a local Zuplo server before deploying anywhere.
@@ -17,7 +20,16 @@ local-test:
   script:
     - npm install
     - npx zuplo dev &
-    - sleep 10
+    # Poll until the server answers, with a hard deadline — never a fixed sleep
+    - |
+      deadline=$((SECONDS + 60))
+      until curl --fail --silent --output /dev/null http://localhost:9000/health; do
+        if (( SECONDS >= deadline )); then
+          echo "Local server did not start within 60s" >&2
+          exit 1
+        fi
+        sleep 1
+      done
     - npx zuplo test --endpoint http://localhost:9000
     - kill %1
 
@@ -34,6 +46,12 @@ deploy:
 
 Local tests run first. Only if they pass does deployment proceed.
 
-## Next Steps
+The readiness poll replaces a fixed `sleep`. A sleep is a guess about startup
+time that is wrong in both directions, and it is the most common reason a
+gateway test suite "needs" a retry. The example polls `/health` — add an
+unauthenticated health route if your gateway does not have one. See
+[health checks](../health-checks.mdx).
+
+## Next steps
 
 - Add [multi-stage deployment](./multi-stage-deployment.mdx) with staging

package/docs/articles/github-deployment-testing.mdx

@@ -1,27 +1,31 @@
 ---
-title: Testing GitHub Deployments
-sidebar_label: Testing Deployments
+title: Test GitHub deployments
+sidebar_label: Test deployments
+description:
+  Trigger a GitHub Actions workflow on Zuplo's deployment_status event, run your
+  test suite against the preview URL, and make the result a required status
+  check so a gateway regression blocks the merge.
 ---
 
 Run your test suite automatically after every Zuplo deployment without replacing
 the built-in GitHub integration. This approach uses GitHub's `deployment_status`
-event to trigger tests after Zuplo finishes deploying.
+event to trigger tests after Zuplo finishes deploying, and makes the result a
+required status check so a gateway regression blocks the merge.
 
-## Why This Approach?
+## Why trigger on deployment_status
 
-Zuplo's GitHub integration already handles deployments perfectly — every push
-deploys automatically with status checks in GitHub. Rather than replacing this
-with custom CI/CD, you can extend it by running tests after each deployment
-completes.
+Zuplo's GitHub integration handles deployments — every push deploys
+automatically with status checks in GitHub. Rather than replacing this with
+custom CI/CD, extend it by running tests after each deployment completes.
 
 This gives you:
 
-- **Automatic deployments** — Keep the built-in integration
-- **Post-deploy testing** — Run tests against the live environment
-- **PR checks** — Tests block merging until they pass
-- **No duplicate deploys** — Tests run after Zuplo deploys, not instead of
+- **Automatic deployments** — keep the built-in integration
+- **Post-deploy testing** — run tests against the live environment
+- **PR checks** — tests block merging until they pass
+- **No duplicate deploys** — tests run after Zuplo deploys, not instead of
 
-## Setup
+## Set up the workflow
 
 Create a workflow that triggers on the `deployment_status` event:
 
@@ -33,11 +37,14 @@ on:
 
 jobs:
   test:
-    # Only run when Zuplo deployment succeeds
+    name: Test API Gateway
+    # Only run when a Zuplo deployment succeeds and reports a URL
     if: |
       github.event.deployment_status.state == 'success' &&
       github.event.deployment_status.environment_url != ''
     runs-on: ubuntu-latest
+    env:
+      API_URL: ${{ github.event.deployment_status.environment_url }}
     steps:
       - uses: actions/checkout@v4
 
@@ -46,29 +53,74 @@ jobs:
           node-version: 24
 
       - name: Install dependencies
-        run: npm install
+        run: npm ci
+
+      # A deployment reporting success is not the same as a gateway
+      # serving traffic. Poll with a hard deadline instead of sleeping.
+      - name: Wait for the gateway to be ready
+        run: |
+          deadline=$((SECONDS + 120))
+          until curl --fail --silent --output /dev/null "$API_URL/health"; do
+            if (( SECONDS >= deadline )); then
+              echo "Gateway at $API_URL not ready after 120s" >&2
+              exit 1
+            fi
+            sleep 2
+          done
 
       - name: Run tests
-        run:
-          npx zuplo test --endpoint ${{
-          github.event.deployment_status.environment_url }}
+        run: npx zuplo test --endpoint "$API_URL"
 ```
 
-## How It Works
+The workflow reads the deployment URL once into `API_URL` and reuses it, so the
+readiness check and the test run target the same environment.
 
-1. You push code to GitHub
-2. Zuplo's integration deploys automatically
-3. Zuplo reports deployment status back to GitHub
-4. The `deployment_status` event triggers your workflow
-5. Your tests run against the deployed environment URL
-6. Test results appear as a check on the commit/PR
+:::caution{title="Poll for readiness, never sleep"}
+
+`deployment_status` fires when the deployment is _accepted_, which can be
+shortly before the environment is warm. A fixed `sleep` is a guess that is wrong
+in both directions — flaky when the system is slow, wasted CI minutes when it is
+fast. Tests fired into that gap fail, get retried, and the pipeline race gets
+misfiled as flaky tests.
+
+If your gateway has no unauthenticated health route, add one. See
+[health checks](./health-checks.mdx).
+
+:::
+
+## How it works
+
+1. You push code to GitHub.
+2. Zuplo's integration deploys automatically.
+3. Zuplo reports deployment status back to GitHub.
+4. The `deployment_status` event triggers your workflow.
+5. The workflow polls the deployment until it answers.
+6. Your tests run against the deployed environment URL.
+7. Test results appear as a check on the commit or pull request.
 
 The `environment_url` from the deployment status contains your Zuplo environment
 URL, so tests always run against the correct environment.
 
-## Filtering by Environment
+## Pass fixture credentials
+
+Tests that exercise authenticated routes need fixture tokens or API keys. Keep
+them in GitHub Actions secrets and pass them as environment variables. Inside
+the test they are available on `TestHelper.environment`:
 
-To only test specific environments (like staging or production):
+```yaml
+- name: Run tests
+  env:
+    TENANT_A_JWT: ${{ secrets.PREVIEW_TENANT_A_JWT }}
+  run: npx zuplo test --endpoint "$API_URL"
+```
+
+API key buckets and rate limit state are per environment, so the credentials
+must belong to the environment being tested. See
+[testing preview environments](./testing-preview-environments.mdx).
+
+## Filter by environment
+
+To test specific environments only, such as staging or production:
 
 ```yaml
 jobs:
@@ -79,15 +131,44 @@ jobs:
     # ...
 ```
 
-## Adding to PR Checks
+Against production, run only the read-only smoke subset rather than the whole
+suite:
+
+```yaml
+- name: Run smoke tests
+  run: npx zuplo test --endpoint "$API_URL" --filter "smoke"
+```
+
+## Add to PR checks
 
 GitHub automatically shows deployment status checks on pull requests. Your test
 workflow results appear alongside them, giving reviewers confidence that both
 deployment and tests succeeded.
 
-## When to Use Custom CI/CD Instead
+To make the check blocking, add the workflow's job name to
+[branch protection](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)
+as a required status check. The example below marks both "Zuplo Deployment" and
+"Test API Gateway" as required.
+
+![Require status checks](../../public/media/testing/a1d7c322-125d-4d80-add0-fbfb65ccfea1.png)
+
+A developer who tries to merge before the tests pass sees the merge blocked.
+
+![Test failure](../../public/media/testing/3f3292a3-075c-4568-afb2-00c24e704f03.png)
 
-This approach works great when you want to:
+:::warning
+
+Do not add a blanket retry to the test job. If a test needs a rerun to pass, it
+has a shared resource, a sleep, or the pipeline is reporting readiness before
+the gateway is serving. A retry converts a debuggable signal into permanent
+background noise. See [gateway test recipes](./testing-recipes.mdx) for the
+determinism rules.
+
+:::
+
+## When to use custom CI/CD
+
+This approach works well when you want to:
 
 - Keep automatic deployments
 - Run tests after deploy
@@ -96,6 +177,12 @@ This approach works great when you want to:
 Consider [custom GitHub Actions](./custom-ci-cd-github.mdx) if you need:
 
 - Approval gates before production
-- Multi-stage deployments (staging → production)
+- Multi-stage deployments (staging then production)
 - Tests that must pass before any deployment
 - Tag-based or release-based deployments
+
+## Related
+
+- [Testing overview](./testing.mdx)
+- [Get started with zuplo test](./testing-getting-started.mdx)
+- [Testing preview environments](./testing-preview-environments.mdx)