Fail unsafe Playwright tests at the fixture boundary

A staging test starts with a production baseURL. The first write could alter live data, so an assertion after login is already too late. The fixture must reject the environment before the test body gets a page capable of doing damage.

Playwright 1.60 added test.abort() for this kind of unrecoverable misuse inside a fixture or route handler, and it is not a replacement for ordinary assertions.

Use abort only when continuing would invalidate the test

test.abort(message?) aborts the currently running test by throwing an error. Playwright marks the test failed immediately, execution stops, and the optional message is included in the failure. The API is intentionally blunt.

Good abort conditions are framework invariants that make all later results untrustworthy:

• The configured target is not on the explicit non-production allowlist.
• A destructive endpoint is called without the isolation mode required by the suite.
• A fixture detects that a shared resource belongs to another worker.
• A route handler sees a request that the test contract forbids under every circumstance.
• Required guard configuration is missing, so the fixture cannot determine whether execution is safe.

Ordinary product failures still belong in expect. A locator assertion explains expected and actual user-visible state and benefits from Playwright's retrying assertion behavior. test.abort() has no expected-versus-actual model; it says the framework refuses to continue.

The distinction from nearby APIs is practical:

• test.skip() marks a test inapplicable and does not report a failure. Use it for a supported condition where not running is acceptable.
• test.fail() marks a test as expected to fail and verifies that it does fail. It is for acknowledged defects or configuration-specific expectations, not unsafe execution.
• expect.soft() records an assertion failure and continues, which is the opposite of a safety stop.
• route.abort() stops a routed network request but does not, by itself, express that the whole test must fail.
• throw new Error() remains a valid failure mechanism and is the compatibility fallback for Playwright versions before 1.60. The dedicated API communicates the guard's intent to readers.

Check the installed project package before adding the call:

npx playwright --version
npx playwright test --help

Do not work around an older type definition with (test as any).abort(). A cast can compile while the runtime still lacks the method. Upgrade the runner and its Playwright packages together, or keep a normal thrown error until the suite moves to 1.60 or later.

Aborting early reduces the amount of evidence produced after the violation. Attach small, sanitized facts before calling it. Never include authorization headers, cookies, complete request bodies, or credentials just because the test is about to stop.

Reject an unsafe target in an automatic fixture

An automatic fixture is a strong place for an environment gate because every test importing that extended test receives the check without naming a fixture argument. It should depend only on configuration needed to decide safety, then call use() when the target is allowed.

This example accepts three explicit local or staging hosts. Replace them with the exact hosts owned by your organization. Exact membership is safer than a loose substring such as hostname.includes('staging').

// fixtures/safe-test.ts
import { test as base, expect } from '@playwright/test';

type SafetyFixtures = {
  safeTarget: void;
};

const allowedHosts = new Set([
  '127.0.0.1',
  'localhost',
  'staging.example.internal',
]);

export const test = base.extend<SafetyFixtures>({
  safeTarget: [async ({ baseURL }, use, testInfo) => {
    let origin = 'missing or invalid baseURL';
    let allowed = false;

    if (baseURL) {
      try {
        const target = new URL(baseURL);
        origin = target.origin;
        allowed = allowedHosts.has(target.hostname);
      } catch {
        allowed = false;
      }
    }

    if (!allowed) {
      await testInfo.attach('target-guard.txt', {
        body: Buffer.from(`Rejected target origin: ${origin}\n`),
        contentType: 'text/plain',
      });
      test.abort(`Refusing to run against ${origin}`);
    }

    await use();
  }, { auto: true }],
});

export { expect };

The attachment stores only the origin, which omits path, query, fragment, and embedded application data. In a real framework, reject URLs containing user information as well and keep secrets out of the message.

Tests import from the fixture module:

// tests/customer-note.spec.ts
import { test, expect } from '../fixtures/safe-test';

test('adds a note to the isolated customer', async ({ page }) => {
  await page.goto('/customers/test-customer-1842');
  await page.getByRole('button', { name: 'Add note' }).click();
  await page.getByLabel('Note').fill('Created by automated test');
  await page.getByRole('button', { name: 'Save note' }).click();
  await expect(page.getByRole('status')).toHaveText('Note saved');
});

The guard covers only files that import this extended test. A single direct import from @playwright/test bypasses it. Enforce the import boundary through code review, an existing lint rule if the repository has one, or a focused text check in CI. Do not claim that defining a fixture in one file changes every Playwright test globally.

Absolute URLs are another bypass. A safe baseURL does not stop a test from calling page.goto('https://production.example.com'), nor does it constrain a separate API client automatically. Inventory absolute navigation and request helpers during rollout. The fixture is one layer, not a network sandbox.

The gate also needs a policy for local aliases and preview environments. Add exact, authenticated preview origins through trusted CI configuration. Avoid accepting arbitrary subdomains merely because they end in a company domain; production often shares that suffix.

Reject a shared fallback namespace

Environment safety is not only about hosts. Parallel tests can damage each other when a missing run identifier makes every worker fall back to a namespace such as default. Abort instead of manufacturing a shared value.

This fixture validates a CI-provided run ID, then derives a per-attempt namespace from Playwright's test identity, parallel index, and retry number. The hash keeps the server-side name compact without exposing the full test title.

// fixtures/isolated-namespace.ts
import { createHash } from 'node:crypto';
import { test as guardedBase } from './safe-test';

type NamespaceFixtures = {
  testNamespace: string;
};

export const test = guardedBase.extend<NamespaceFixtures>({
  testNamespace: async ({ safeTarget }, use, testInfo) => {
    void safeTarget;
    const runId = process.env.TEST_RUN_ID;

    if (!runId || !/^[a-z0-9-]{8,48}$/.test(runId)) {
      await testInfo.attach('namespace-guard.txt', {
        body: Buffer.from('TEST_RUN_ID is missing or invalid\n'),
        contentType: 'text/plain',
      });
      test.abort('Refusing to use a shared fallback test namespace');
    }

    const attemptKey = [
      testInfo.testId,
      testInfo.parallelIndex,
      testInfo.retry,
    ].join(':');
    const suffix = createHash('sha256')
      .update(attemptKey)
      .digest('hex')
      .slice(0, 12);

    await use(`${runId}-${suffix}`);
  },
});

The fixture does not create or delete server data by itself. A data fixture should depend on testNamespace, provision resources under that value, and clean the same value in finally. The abort happens before provisioning, which is the safest point to discover missing isolation configuration.

Cleanup must also verify that it is deleting only its assigned namespace. Do not let a missing variable broaden a server query or filesystem path. Validate the exact identifier again at the destructive boundary, and make the server reject deletion outside the test account's permitted prefix. Fixture validation catches mistakes early; the resource service still owns authorization.

Including testInfo.retry gives a retry a different namespace. That improves isolation from a dirty first attempt but increases cleanup volume. If the product workflow requires a retry to inspect or resume the first attempt's data, keep the namespace stable and make that choice explicit. Do not accidentally reuse state because a worker restart retains the same parallel index.

The regular expression is a naming policy, not a security proof. Server authorization still needs to restrict what the test account can access. Its value is removing the silent default branch that turns a CI configuration error into cross-test contamination.

Stop a forbidden request and fail the test that made it

A route guard catches misuse closer to the dangerous action. It is useful when most POST requests are legitimate but one endpoint must never be reached from a shared test account.

Block the request first, attach minimal metadata, then abort the test. Calling only test.abort() relies on the thrown error to interrupt the handler; explicitly aborting the route makes the network decision clear.

// fixtures/publish-guard.ts
import {
  test as safeBase,
  type Route,
} from './safe-test';

type PublishGuardFixture = {
  publishGuard: void;
};

const publishPattern = '**/api/shared/publish';

export const test = safeBase.extend<PublishGuardFixture>({
  publishGuard: [async ({ page, safeTarget }, use, testInfo) => {
    void safeTarget;
    const guard = async (route: Route) => {
      const request = route.request();
      if (request.method() !== 'POST') {
        await route.fallback();
        return;
      }

      await testInfo.attach('blocked-publish.json', {
        body: Buffer.from(JSON.stringify({
          method: request.method(),
          url: request.url(),
        }, null, 2)),
        contentType: 'application/json',
      });

      await route.abort('blockedbyclient');
      test.abort(
        'Blocked POST /api/shared/publish. Use an isolated draft fixture.',
      );
    };

    await page.route(publishPattern, guard);
    try {
      await use();
    } finally {
      await page.unroute(publishPattern, guard);
    }
  }, { auto: true }],
});

route.abort('blockedbyclient') uses a documented route error code. For non-POST requests, route.fallback() allows another matching route handler to run before the request goes to the network. That choice matters in suites that layer mocks and guards. route.continue() would send the request immediately and other matching handlers would not be invoked.

Route handlers with the same match run in reverse registration order. A guard that must be the final authority needs a tested registration strategy, not an assumption about file import order. Write a fixture contract test alongside any layered routing setup.

The route guard has a serious boundary: browser routing is test instrumentation, not a security control. Service workers and other traffic paths can affect what a given route sees, and the matcher protects only the endpoint patterns it names. Keep the target allowlist, server-side test-account permissions, and isolated data design. A client-side route should be defense in depth, never the only barrier between automation and production.

An APIRequestContext is another distinct path. Calls made through Playwright Test's request fixture do not travel through a page route. If tests use direct API setup, expose a narrow guarded client rather than assuming the browser handler covers it.

// fixtures/guarded-api.ts
import type { APIResponse } from '@playwright/test';
import { test as guardedBase } from './publish-guard';

type GuardedApi = {
  post(path: string, data: unknown): Promise<APIResponse>;
};

type ApiFixtures = {
  guardedApi: GuardedApi;
};

export const test = guardedBase.extend<ApiFixtures>({
  guardedApi: async ({ request, baseURL, safeTarget }, use, testInfo) => {
    void safeTarget;
    if (!baseURL) {
      test.abort('guardedApi requires a configured baseURL');
    }

    await use({
      async post(path, data) {
        const target = new URL(path, baseURL);
        if (target.pathname === '/api/shared/publish') {
          await testInfo.attach('blocked-api-call.json', {
            body: Buffer.from(JSON.stringify({
              method: 'POST',
              origin: target.origin,
              pathname: target.pathname,
            }, null, 2)),
            contentType: 'application/json',
          });
          test.abort('Blocked direct API publish to the shared resource');
        }

        return request.post(target.toString(), { data });
      },
    });
  },
});

This wrapper intentionally exposes less than the underlying request context. That constraint is the point: setup code gets the operations the suite permits. The cost is extra framework code and occasional additions when a legitimate method is needed. Returning the raw request object beside the wrapper would make bypass trivial and defeat the design.

The wrapper still is not a universal firewall. A test can import another request library, open a WebSocket, or use an absolute browser URL unless repository policy controls those paths. Pair the narrow API with least-privileged test credentials and server-side authorization. A guardrail should fail obvious misuse early while durable controls make the same misuse harmless.

The attachment in this example includes a URL. If query parameters can contain tokens or customer data, sanitize it to origin and pathname before attaching. Evidence should identify the blocked operation without creating a second incident in the report.

Handle fixture setup, teardown, and asynchronous callbacks honestly

Calling test.abort() throws. Code after the call in that execution path does not run, so cleanup belongs in finally blocks around use() and registered handlers must be removed by their owner.

The target gate aborts before use(), which means it has not exposed a resource that needs teardown. The publish guard installs a page route, calls use(), and removes the exact handler in finally. That structure remains readable whether the test passes, an assertion fails, or the route guard aborts.

Avoid detached background callbacks. test.abort() applies to the currently running test. A timer or event listener that fires after the fixture has finished no longer has a safe current-test boundary. Scope listeners to the fixture, remove them before teardown ends, and make browser operations that trigger them part of awaited Playwright actions.

A near-miss occurs when a route callback starts asynchronous evidence collection without awaiting it:

// Wrong: attachment work races the abort and its rejection is not awaited here.
page.on('request', request => {
  if (request.url().includes('/api/shared/publish')) {
    void testInfo.attach('request.txt', {
      body: Buffer.from(request.url()),
      contentType: 'text/plain',
    });
    test.abort('Forbidden publish request');
  }
});

Use an awaited route handler for a request that must be stopped. The handler can await attachment creation and route.abort() before invoking test.abort(). A passive request event is useful for observation, but it does not give the test a Route to block.

Another near-miss is aborting in teardown because cleanup found stale data. At that point the product assertion has already run, but the test attempt still has an invalid cleanup result. Failing is appropriate; however, preserve the cleanup error itself when it is more specific than a generic guard message. A normal thrown error may be clearer when an API cleanup call returns a detailed failure. Use test.abort() for the explicit decision to halt, not to erase a useful exception.

If several fixtures can abort, make messages unique and actionable. Unsafe configuration sends a reviewer searching. Refusing to run against https://production.example.com identifies the rejected value and owner. Keep the message concise because it appears in terminal and HTML reports.

Prove the guard ran before mutating setup

A report can show the expected abort message and still describe a guard that ran too late. The second failure mode is a worker-scoped automatic fixture that provisions an account, seeds data, or opens an API client before the test-scoped target guard starts. Playwright sets up automatic worker fixtures before test-scoped fixtures. An empty test trace and a test body that never ran do not prove that earlier fixture setup made no request.

This can present almost exactly like a successful safety rejection. The line reporter names the target guard, the sanitized origin attachment is present, and the test ends as failed. The different root cause sits before that evidence: a broader fixture performed a mutation while resolving its own setup. By the time safeTarget aborts, stopping the test body only prevents later work.

Separate the cases with phase evidence from the earliest resource owner. For a healthy rejection, the first application-facing fixture record should be the validation decision, and there should be no account, tenant, or dataset creation for that test run. For a late guard, the test-support service or fixture log contains a create operation before the target-guard record. Use a shared run identifier or other existing correlation evidence to connect the operation without copying credentials into the report.

The important field in target-guard.txt remains the sanitized origin. A production origin proves why the test-scoped guard refused to continue. It does not prove when every other fixture ran. A value such as missing or invalid baseURL identifies a configuration parse failure, not a positive production match. Keep those two values distinct so CI configuration owners do not receive an incident that belongs to an unsafe target, or the reverse.

Several signals are misleading on their own. testInfo.status records the final test outcome, not the absence of earlier side effects. A trace with no page actions says the test body did not navigate, but it may omit API work done by a fixture. A guard attachment timestamp can help, but process clocks and remote-service clocks are not a sufficient ordering contract. The fixture dependency graph and a service-side operation record provide stronger evidence.

A worker-scoped fixture cannot rely on a later test-scoped safety decision. Put pure target validation in a shared function and call it before the broader fixture performs network or filesystem work. Keep the automatic test guard as a second boundary for test-scoped pages and request clients. When a worker fixture has no safe target, fail its setup before it creates the resource. This duplicates a cheap decision across scopes, but it closes the period in which broad setup could act without validation.

That duplication has a concrete maintenance cost. The allowlist policy must remain identical at worker and test boundaries, preview-origin changes must update reviewed configuration, and an incorrectly rejected host can block an entire worker before any product test runs. Centralizing the pure parser and policy prevents two copied host lists from drifting while still requiring each mutating scope to invoke it.

Distinguish a guardrail failure from nearby red tests

An abort failure should point to the guard fixture or route handler and include its message. Diagnose that message before inspecting product selectors. A login timeout after the guard passed is a different problem.

Run one target with a local reporter and retained trace:

npx playwright test tests/customer-note.spec.ts \
  --project=chromium \
  --reporter=line \
  --trace=retain-on-failure

Look for these signals:

• The target guard attachment proves which sanitized origin was rejected.
• A blocked-route attachment proves the request reached the guard and records its method and sanitized URL.
• A trace ending before navigation, with a target-guard failure, is expected because the test body never received permission to proceed.
• A browser network failure without the guard's abort message can be a route abort from another handler, application behavior, or infrastructure failure.
• A skipped result means some skip condition ran; it is not how test.abort() reports unsafe execution.

Retries do not repair deterministic safety conditions. Every new attempt re-runs test-scoped automatic fixtures. If baseURL still points at production, each attempt should abort. This repetition is not flakiness. Disable or limit retries for a small guard-contract project if repeated setup adds noise, but keep the production suite's retry policy separate from guard correctness.

Test the negative path in a child Playwright run so the outer verification expects a nonzero status. This Bash script proves the probe fails for a rejected target and that the message survives:

#!/usr/bin/env bash
set -euo pipefail

set +e
output="$({
  BASE_URL='https://production.example.com' \
    npx playwright test tests/guard-probe.spec.ts --reporter=line
} 2>&1)"
status=$?
set -e

if [[ $status -eq 0 ]]; then
  echo 'Guard probe unexpectedly passed' >&2
  exit 1
fi

grep -Fq 'Refusing to run against https://production.example.com' <<<"$output"
echo 'Guard probe rejected the unsafe target as expected'

The probe test should import the guarded fixture and contain no destructive operation. Its purpose is to prove setup refuses the configuration. Do not point a real mutation test at production to see whether the guard catches it.

Wire the accepted target and run namespace from trusted CI configuration. The Playwright config should map BASE_URL into use.baseURL, while the job supplies a staging-only variable:

- name: Verify the guard rejects a production target
  run: ./scripts/verify-target-guard.sh

- name: Run guarded end-to-end tests
  env:
    BASE_URL: ${{ vars.STAGING_BASE_URL }}
    TEST_RUN_ID: e2e-${{ github.run_id }}-${{ github.run_attempt }}
  run: npx playwright test tests/e2e --project=chromium

Protect the CI variable from untrusted edits, and keep the exact host allowlist in reviewed code. A variable named STAGING_BASE_URL is only a label; the automatic fixture must still parse and validate the resulting origin on every attempt.

Roll the guard out without claiming coverage it does not have

Start with version alignment and a single fixture module. Then inventory how tests import test, where base URLs originate, and which helpers use absolute URLs or separate APIRequestContext instances.

rg -n "from ['\"]@playwright/test['\"]" tests e2e fixtures
rg -n "https?://|baseURL|newContext|request\.newContext" tests e2e fixtures

Replace imports in one high-risk directory, run the negative probe, and confirm normal staging tests still execute. A broad mechanical import rewrite without checking fixture dependencies can change setup order and route layering, so review each framework entry point.

Put the safe-target fixture below all guarded test variants. If adminTest, mobileTest, and apiTest each extend the raw base independently, one of them will eventually omit the guard. Prefer one guarded base that specialized fixtures extend.

Add server-side restrictions as the durable backstop. Test credentials should lack production write access. Destructive tests should operate in namespaces that a worker owns and can delete. Network policy, account policy, and fixture validation solve different failure paths; do not market a Playwright callback as an organizational security boundary.

Watch failure volume during rollout. If many tests abort because baseURL is absent, decide whether those files legitimately use absolute local URLs or bypass configuration accidentally. Add a separate guarded base for a genuine use case rather than weakening the host check for everyone.

Keep report retention long enough for the owning team to see the guard message, but do not retain sensitive request evidence. A small origin or path attachment is normally enough. The guard's value comes from stopping early and naming the violated contract, not from dumping the environment.

For an established suite, land the shared validation function and its accepted and rejected configuration cases first. Then land the negative child-run probe against a test with no destructive body. Only after that proof is stable should specialized fixture exports start extending the guarded base. This order keeps a failure in policy parsing separate from a failure caused by changing hundreds of imports.

Audit automatic worker fixtures before migrating ordinary specs. They execute at the broadest and earliest boundary and are the first place a test-scoped guard cannot provide ordering. Next inspect test-scoped provisioning fixtures and direct API helpers, then add route guards around the small set of browser requests that need last-line blocking. Network interception should not land first because a green route probe says nothing about setup that ran outside the page.

The first rollout breaks usually expose direct imports from the raw runner, preview hosts missing from the exact allowlist, or specialized fixtures that extend an unguarded base. Do not silence those failures with a company-domain suffix. Classify each consumer, add an exact approved target when it is genuinely safe, and keep unsupported fixture trees failing until their ownership is clear.

The rollout is working when every supported fixture variant rejects the negative probe before any application mutation, normal staging tests reach their unchanged assertions, and blocked routes carry both the guard-specific message and sanitized operation attachment. Review server-side audit evidence for the probe, not only the Playwright exit status. A deterministic abort on every retry confirms consistency, but it does not prove early ordering by itself.

Test-platform maintainers own the fixture graph, guarded import boundary, and route-handler disposal. CI or environment-platform owners own the trusted target variables and job-level network policy. Application service owners own least-privileged test accounts and server-side authorization. A handoff should include the sanitized resolved origin, project and attempt, fixture name and scope, the first application operation observed, the guard attachment, the failure stack, and whether the operation occurred before or after validation. It should never include the credential or complete request body.

This guard does not catch work that runs before Playwright fixtures exist. A shell step, global setup program, database migration, or separate test tool can mutate an unsafe environment before safeTarget has a current test to abort. Those entry points need their own target validation and server-side permissions. Importing the guarded test cannot protect another process.

Know when abort is the wrong failure tool

Use expect when the test can continue safely long enough to report a product mismatch. A failed heading, response status, or saved value deserves expected and actual evidence rather than a generic stop.

Use test.skip() when a documented configuration makes the test inapplicable and the delivery policy accepts that. Do not skip because a required staging service was misconfigured; that converts lost coverage into a non-failing result.

Avoid abort for transient readiness. If a service may become healthy within an agreed startup window, use the fixture's awaited readiness check and let its timeout explain the failure. Aborting on the first unsuccessful probe defeats retrying web-first behavior.

Do not add route guards as the sole control for production protection. They cover named browser requests observed by that routing layer, not every process, protocol, service worker, or helper client in the test system. Exact environment validation and least-privileged credentials remain necessary.

Finally, do not abort merely to shorten a test after a soft assertion. If continuing is safe and later evidence helps diagnose the same product defect, let the test finish according to its assertion strategy. Reserve immediate failure for conditions where every subsequent result would be unsafe, misleading, or both.