Playwright Specs

This is one of the fastest ways to create Playwright Specs by recording browser interactions.

1. Create and open an empty project folder:

mkdir playwright-specs
cd playwright-specs

2. Initialize a Node.js project:

npm init -y

3. Set up Playwright:

npm init playwright@latest

4. Once Playwright is installed, start Codegen against your target application:

npx playwright codegen https://your-target-url.com

This opens a browser and begins recording your actions. As you interact with the application, Playwright generates the corresponding test steps.

5. Create a spec file inside your tests folder and save the generated steps into it, for example:

mkdir -p tests

6. Save the recorded flow into a file such as:

tests/login-flow.spec.ts

7. Run the spec to confirm it works:

npx playwright test

For more information, Refer https://playwright.dev/docs/codegen#generate-tests-with-the-playwright-inspector

This method is useful when you want agent-assisted help to create Playwright Specs from scratch. Playwright provides three built-in test agents: planner, generator, and healer. The usual flow is to let the planner explore the app and produce a Markdown test plan, then let the generator turn that plan into Playwright Test files, and finally use the healer to repair failing tests.

1. Create and open an empty project folder.

mkdir playwright-specs
cd playwright-specs

2. Initialize a Node.js project.

npm init -y

3. Create a Playwright project.

npm init playwright@latest

This creates the base Playwright project structure so you can start generating tests.

4. Generate the Playwright agent definitions for VS Code.

npx playwright init-agents --loop=vscode

Playwright recommends regenerating these agent definitions whenever Playwright is updated so the agents pick up new tools and instructions. VS Code version 1.105 or later is required for this agentic experience.

npx playwright init-agents --loop=vscode

5. Create a seed test.

The planner expects a seed test that sets up the environment needed to interact with your app. Playwright states that the planner uses this test to run initialization such as global setup, project dependencies, fixtures, and hooks, and also uses it as an example for generated tests.

Create a simple seed test such as:

import { test } from '@playwright/test';

test('seed', async ({ page }) => {
  await page.goto('https://your-app-url.com');
});

Save it as:

tests/seed.spec.ts

6. Ask the planner to create a bounded and precise plan.

The planner explores your app and produces a Markdown test plan for one or more scenarios and user flows. It works best when the request is narrow and explicit. Avoid vague requests like “cover the whole app.” Instead, tell it exactly what flow should be automated, where it starts, what success looks like, and which seed test it should use.

A very basic prompt can be:

Generate a plan for a Playwright spec that logs into the application, opens the billing page, verifies that the invoices table is visible, and logs out. Use tests/seed.spec.ts as the seed test. Keep the plan focused only on this flow.

Bounded, precise planner tasks usually give better results than broad ones.

7. Review the generated Markdown plan.

The planner produces a human-readable Markdown plan under specs/, such as specs/basic-operations.md. Review it before continuing and make sure it matches the exact workflow you want.

8. Pass the approved plan to the generator.

The generator takes the Markdown plan from specs/ and converts it into executable Playwright Test files under tests/. Playwright notes that the generator verifies selectors and assertions live while performing the scenarios.

Your end result should be a clean spec file such as:

tests/billing-flow.spec.ts

9. Run the generated tests.

npx playwright test

Or run only the generated spec:

npx playwright test tests/billing-flow.spec.ts

10. Use the healer if the spec fails.

When a test fails, the healer replays the failing steps, inspects the current UI, suggests a patch such as a locator update or wait adjustment, and reruns the test until it passes or until its guardrails stop the loop.

11. Review the healed result and make manual corrections where needed.

The healer can fix many practical issues, but it should not replace human review. After healing, check whether the final test is still doing exactly what you intended. If selectors, waits, assertions, or flow logic still need adjustment, update the spec manually and run it again.

12. Repeat the same flow for additional user journeys.

This workflow works best when the requested plan is bounded and precise. Smaller, clearly defined flows are easier for the planner to map, easier for the generator to turn into useful specs, and easier for the healer to fix when something breaks. This also aligns with Playwright’s documented flow of planner to generator to healer producing test coverage sequentially.

For more information, Refer https://playwright.dev/docs/test-agents

Before importing a JavaScript or TypeScript Playwright project, configure it so browser traffic is routed through the ZeroThreat scanning engine.

At the top of your playwright.config.ts, make sure devices is imported:

import { defineConfig, devices } from '@playwright/test'

In your default Playwright configuration, keep the project running in headless mode. If you already have headless: true set, keep it as it is. Otherwise, do not explicitly add or override this setting.

You should also structure your Playwright project so that each individual spec completes within 30 seconds. This is the timeout used for Playwright Spec execution inside ZeroThreat. You can have as many individual specs as needed, but each spec should stay within that limit to ensure the best coverage.

Inside your playwright.config.ts, add the following project configuration under projects:

{
    name: 'ZT-Proxy-Chromium',
    use: {
        ...devices['Desktop Chrome'],
        proxy: {
            server: 'http://localhost:8000',
        },
        ignoreHTTPSErrors: true,
    },
}

This ensures that Playwright traffic flows through the ZeroThreat scanning engine.

Inside your package.json, add the following script under scripts:

"zt:test": "npx playwright test --project=ZT-Proxy-Chromium"

After these changes, your existing Playwright Specs will automatically execute within ZeroThreat without requiring any modifications to your test spec logic.

ZeroThreat also supports Playwright Specs written in Python, including projects using pytest, pytest-playwright, direct Playwright APIs, or custom test runners.

Python Project Detection

Python projects are automatically detected when the selected repository path or uploaded project contains one of the following files:

• requirements.txt
• pyproject.toml
• uv.lock

If a package.json is present at the same project level, the project is not automatically treated as a Python project.

Dependency Files

Your Python project must contain at least one supported dependency file at the project root or configured repository path:

• requirements.txt
• pyproject.toml
• uv.lock

ZeroThreat installs the project dependencies automatically before executing the tests, including the required Playwright browsers.

Choosing How Your Tests Run

ZeroThreat needs to determine which command should execute your test suite.

There are two supported approaches.

Option 1: Standard pytest projects

If your project uses a standard pytest setup, including pytest-playwright fixtures or direct use of sync_playwright(), ZeroThreat automatically detects the project style and executes the tests.

No additional ZeroThreat configuration is required.

Option 2: Custom test command

If your project does not use a standard pytest setup, you can explicitly define the command ZeroThreat should execute.

This can be useful for projects using:

• behave
• Robot Framework
• tox
• nox
• custom CLI wrappers
• custom test entrypoints
• non-standard pytest commands

Add a [tool.zerothreat] section to your pyproject.toml:

[tool.zerothreat]
test_command = "python -m pytest -m 'not flaky' --tb=short"

ZeroThreat runs the command exactly as configured inside the project's Python environment, with the scanning proxy already active.

Getting Spec-Level Reporting

For the best visibility in the Scan Report, your test run should generate a pytest-json-report compatible report.json.

This allows ZeroThreat to associate execution results and network activity with individual specs instead of only recording the overall test run result.

For standard pytest projects, this is handled automatically.

If you use a custom test_command, include:

--json-report --json-report-file=report.json

For example:

[tool.zerothreat]
test_command = "python -m pytest -m 'not flaky' --tb=short --json-report --json-report-file=report.json"

Without this report, ZeroThreat can still determine whether the overall test command passed or failed, but individual spec-level results cannot be displayed.

Python Test Execution Requirements

Python Playwright projects should run their tests serially.

Avoid parallel execution plugins or options such as:

pytest -n auto

Parallel execution may cause network activity generated by one test to be incorrectly attributed to another spec in the Scan Report.

Keep each test focused on a specific workflow and avoid combining several large business flows into a single test.