# Playwright reporter

Source: https://docs.qualflare.com/docs/reporters/playwright · Last updated: 2026-10-29

Install @qualflare/playwright, add it to playwright.config.ts and upload its qualflare-results folder with the Qualflare CLI, sharded runs included.

`@qualflare/playwright` is the Qualflare reporter for Playwright Test 1.40 or later: it writes each run's results, with nested `test.step()` trees, per-attempt retries, screenshots, videos and traces, to `./qualflare-results`, and `qf <identifier> collect` uploads the folder as one launch.

| Fact                 | Detail                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| Package              | [`@qualflare/playwright`](https://www.npmjs.com/package/@qualflare/playwright) on npm                           |
| Works with           | `@playwright/test` 1.40 or later, Node.js 18 or later (Playwright 1.62 and later need Node.js 20)               |
| qf                   | (requires qf 0.1.24 or later)                                                                                   |
| License              | Apache-2.0                                                                                                      |
| Source               | [Qualflare/qualflare-playwright](https://github.com/Qualflare/qualflare-playwright) on GitHub                   |
| Without the reporter | `--format playwright` with [Playwright's JSON reporter](https://docs.qualflare.com/docs/cli/formats#playwright) |

## Before you begin

* The Qualflare CLI, `qf`: [Install the CLI](https://docs.qualflare.com/docs/cli/installation).
* A saved login: `qf login <identifier>` with a project access token whose creator still holds the project role that uploads need (requires the Editor role or higher in the project) ([Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication)).
* The **Identifier** of the environment the results belong to ([Environments](https://docs.qualflare.com/docs/runs/environments#identifier)).

## Install

```bash
npm install --save-dev @qualflare/playwright
```

## Configure

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { qualflareReporter } from '@qualflare/playwright';

export default defineConfig({
  reporter: [['list'], qualflareReporter({ environment: 'staging' })],
});
```

The tuple form works too: `['@qualflare/playwright/reporter', { environment: 'staging' }]`.

| Option | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `includeApiSteps` | `boolean` | `false` | No | Report Playwright's `pw:api` and `fixture` steps too. A failed one is always reported. Variable `QUALFLARE_INCLUDE_API_STEPS`. |
| `attachScreenshots` | `boolean` | `true` | No | `false` skips every attachment, videos included. Variable `QUALFLARE_ATTACH_SCREENSHOTS`. |
| `maxTraceBytes` | `number` | `52428800` | No | Skips a larger trace before copying it. Variable `QUALFLARE_MAX_TRACE_BYTES`. |
| `maxVideoBytes` | `number` | `52428800` | No | The same for a video. Variable `QUALFLARE_MAX_VIDEO_BYTES`. |

A relative `outputDir` resolves against the folder of your Playwright config, not the shell's working directory.

Every reporter shares the other settings: see [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration).

Set `environment` to the environment's Identifier: a name such as `Staging` fails the upload with HTTP 400 ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).

## Run and upload

```bash
npx playwright test
qf <identifier> collect ./qualflare-results
```

Screenshots upload by default. Add `--upload-artifacts video,trace` to upload videos and traces; `qf` prints how many it skipped otherwise.

## Run in CI

```yaml
- name: Upload results to Qualflare
  if: ${{ !cancelled() }}
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
    QF_BRANCH: ${{ github.head_ref || github.ref_name }}
    QF_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
  run: |
    npm install -g @qualflare/cli
    qf login ci --force
    qf ci collect ./qualflare-results
```

`if: ${{ !cancelled() }}` uploads the results when tests fail, and `QF_BRANCH` and `QF_COMMIT` record a pull request's own branch and commit ([Pull request branches](https://docs.qualflare.com/docs/cli/ci-cd#pull-request-branches)). For GitLab CI/CD, Jenkins and Azure Pipelines, see [Run the upload when tests fail](https://docs.qualflare.com/docs/cli/ci-cd#run-when-tests-fail).

## Sharding and retries

Point every shard at the same folder. Playwright passes its own `--shard` value to the reporter, which stamps each test with a 0-based shard index, so nothing needs configuring. Playwright's `merge-reports` mode and `blob` reporter aren't supported: use the folder. [Merge sharded CI jobs into one launch](https://docs.qualflare.com/docs/cli/sharding#merge-sharded-ci-jobs) has a GitHub Actions example with this reporter.

Each attempt's status, duration and error is uploaded; steps, labels, tags and attachments come from the final attempt. A test that ran once sends no attempts.

## What gets uploaded

* Status, with the history of each retried attempt.
* Nested steps. `qualflare.step()` runs Playwright's own `test.step()`, so the steps also show in Playwright's HTML report and trace viewer.
* Screenshots, videos and traces.
* Labels, links, tags, priority and parameters.

A test sets its own metadata with the `qualflare` calls:

```typescript
import { test } from '@playwright/test';
import { qualflare } from '@qualflare/playwright';

test('a user can check out @smoke', async ({ page }) => {
  qualflare.label('epic', 'Billing');
  qualflare.link('https://tracker.example/QF-42', { type: 'issue', name: 'QF-42' });
  qualflare.priority('high');

  await qualflare.step('add an item to the cart', async () => {
    qualflare.parameter('sku', 'BOOK-1');
    await page.getByRole('button', { name: 'Add' }).click();
  });
});
```

`qf` doesn't read the branch, commit, language or milestone from the report: set them on the upload ([Branch, commit, language and milestone](https://docs.qualflare.com/docs/reporters/configuration#upload-metadata)).

## Troubleshooting

* Traces are missing: pass `--upload-artifacts trace` to the upload, and use qf 0.1.20 or later.
* Hundreds of steps per test: `includeApiSteps` is on; turn it off.
* `environment "Staging" does not exist in this project`: use the environment's Identifier, or pass `--environment` on the upload ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).
* Screenshots can't be downloaded: `qf` is older than 0.1.24. [Upgrade qf](https://docs.qualflare.com/docs/cli/installation#upgrading).

## Related

* **Guides:** [Reporters](https://docs.qualflare.com/docs/reporters) · [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Sharded runs and result directories](https://docs.qualflare.com/docs/cli/sharding) · [Upload screenshots, videos and traces](https://docs.qualflare.com/docs/cli/artifacts)
* **Reference:** [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration) · [Playwright format](https://docs.qualflare.com/docs/cli/formats#playwright)
* **More:** [Playwright test reporting in Qualflare](https://qualflare.com/playwright-test-reporting/)