Playwright Integration

This documentation explains how to report Playwright automated test results into PractiTest using the Auto Create a Run API.

Use this approach when your Playwright tests run outside PractiTest, for example from a local machine, GitHub Actions, Jenkins, GitLab CI, Azure DevOps, Bamboo, or another CI/CD tool, and you want the results to appear in PractiTest as automated test runs.

With this integration, Playwright remains responsible for running the tests, while PractiTest stores the results, execution history, attachments, and reporting data.

• Setting Up the Custom Reporter
• Mapping Playwright Tests to PractiTest Tests
• Recommended Naming Approach
• Reporting Passed and Failed Results
• Using Playwright With CI/CD
• Sending Attachments
• Recommended First Implementation
• Best Practices
• Related Resources

How It Works

The recommended approach uses a Playwright custom reporter that sends each test result to PractiTest as the test finishes.

Playwright custom reporters can access the result of every test once it completes, including its status, duration, error information, and attachments. The reporter converts that result into a request to the PractiTest Auto Create a Run API, which finds or creates the relevant test and instance and creates the run in one call.

Playwright test finishes:

1.  Reporter’s onTestEnd() receives the result
2.  Reporter converts the result into a PractiTest API request
3.  PractiTest finds or creates the test and instance
4.  PractiTest creates the automated run

This keeps the integration centralized; you do not add PractiTest API calls inside individual Playwright tests.

For a complete, working implementation, see the Playwright example project rather than building the reporter from scratch. It includes a ready-to-adapt custom reporter, PractiTest API calls, and attachment handling.

Prerequisites

Before setting up the integration, make sure you have:

• A PractiTest project and its ID
• A PractiTest Test Set and its ID where Playwright results should be reported
• A PractiTest API token with permission to create runs and, if PractiTest should create missing tests or instances automatically, permission to create those too
• A Playwright project or test suite
• A decision on how to map Playwright tests to PractiTest tests, by test ID or by test name (see below)

Setting Up the Custom Reporter

Register the reporter in playwright.config.ts alongside your other reporters:

Store your PractiTest project ID, Test Set system ID, and API token as environment variables or CI/CD secrets, never commit them to source control. The reporter reads these at runtime and calls the Auto Create a Run API from onTestEnd() for each test.

Mapping Playwright Tests to PractiTest Tests

There are two common ways to map Playwright tests to PractiTest tests.

Option 1: Match by PractiTest Test ID

Use this when your tests already exist in PractiTest and you want strict control over the mapping. Each Playwright test is connected to a specific PractiTest test ID, so PractiTest always knows exactly which test should receive the result.

Best when:

• Your test cases are already managed in PractiTest
• You want to avoid creating new tests automatically
• You need full control over the mapping
• Test names may change over time

Option 2: Match by Playwright Test Name

Use this when you want PractiTest to find or create tests based on the Playwright test name. PractiTest looks for a test with that name and creates one automatically if none exists.

Best when:

• You are starting a new automation integration
• You want a faster setup
• Your Playwright test names are stable and descriptive
• You do not want to maintain a manual mapping file

For the full attribute reference for both options, including test-type, description, and other optional test-attributes, see the Auto Create a Run API documentation.

Recommended Naming Approach

If you use name-based mapping, use a stable, descriptive pattern:

Area / Feature / Scenario

Examples:

• Login / Invalid Password
• Checkout / Apply Discount Code
• User Management / Create User Without Email

For Playwright tests organized with describe blocks, use the full test title path to create a clear, unique PractiTest test name, for example, Authentication > Login validation > rejects invalid password. This avoids duplicate tests and keeps names meaningful in PractiTest.

Reporting Passed and Failed Results

PractiTest uses the exit-code field to determine the run status: 0 reports the run as Passed, and any other value reports it as Failed.

{
  "data": {
    "type": "instances",
    "attributes": {
      "set-id": 12345,
      "exit-code": 0,
      "run-duration": "00:00:12",
      "automated-execution-output": "Playwright test passed"
    },
    "test-attributes": {
      "name": "Login / Valid User Login"
    }
  }
}

For a failed test, send a short failure summary in automated-execution-output. For example, an assertion message, a timeout notice, or the locator that wasn’t found. This field supports up to 255 characters; for full failure detail, use attachments or a link to an external report instead.

Playwright also supports step-level and blocked/skipped statuses. See Reporting Steps in the Auto Create a Run API docs if you want to report at that level of detail.

Using Playwright With CI/CD

The same reporter works unchanged when Playwright runs from a CI/CD pipeline. No pipeline-specific setup is required, since the reporter runs as part of the normal Playwright test process:

CI/CD pipeline starts:

1. Playwright tests run
2. Custom reporter sends each result to PractiTest as tests complete
3. PractiTest shows the latest automated run results

You can also send CI/CD metadata to PractiTest, build number, branch name, commit ID, environment, browser, pipeline URL, as custom fields or as part of the execution output, depending on your reporting needs.

Sending Attachments

Playwright can generate screenshots, traces, and videos as test artifacts. For failed tests, attach these to the PractiTest run so testers and developers can see the failure without leaving PractiTest.

A good first implementation is to attach screenshots only for failed tests. This keeps the integration useful without unnecessary storage or noise. Files are sent Base64-encoded; the maximum attachment size is 50 MB.

Recommended First Implementation

For the first version, keep the integration simple:

1. Report one PractiTest run per Playwright test
2. Use a custom reporter to centralize the reporting logic
3. Use stable Playwright test names, unless you already have PractiTest test IDs
4. Use exit-code to report passed or failed results
5. Send run-duration
6. Add a short automated-execution-output
7. Attach screenshots only for failed tests
8. Add custom fields only when needed for filtering or reporting

After the basic flow is working, expand to include additional metadata, advanced mapping, step-level reporting, or richer attachments.

Best Practices

• Use stable, descriptive Playwright test names if you use name-based mapping
• Use PractiTest test IDs if you need strict control over the mapping
• Keep PractiTest API logic inside the reporter, avoid adding it to individual tests
• Start with test-level reporting before adding step-level reporting
• Attach failure evidence selectively
• Store API tokens securely in environment variables or CI/CD secrets, never commit tokens or .env files to source control
• Use custom fields only when they support reporting, filtering, or traceability

Related Resources

• Auto Create a Run API
• PractiTest API v2 Documentation
• Playwright Custom Reporters
• PractiTest Playwright Example Project