How to Rerun Failed Test Cases in Playwright

Use npx playwright test --last-failed to rerun only the tests that failed in the previous Playwright Test run. Playwright reads the prior run record from <outputDir>/.last-run.json. If that record is elsewhere, pass --last-failed-file <file> or set PLAYWRIGHT_LAST_RUN_OUTPUT_FILE.

This is different from retries. --last-failed replays failures from a completed run; retries rerun a test while the current command is still running.

Rerun failures from the previous run

Run the full suite once so Playwright writes its last-run file.
Fix or inspect the environment, then run:

npx playwright test --last-failed

You can combine it with normal filters:

# One project
npx playwright test --last-failed --project=chromium

# Headed or debug rerun
npx playwright test --last-failed --headed
npx playwright test --last-failed --debug

# Use a copied record
npx playwright test --last-failed --last-failed-file=artifacts/run-42/.last-run.json

The record is state from a prior Playwright Test run. Preserve it until the investigation is complete because a new full run can replace the state you intended to replay.

What the last-failed file does

By default, Playwright stores selection data at <outputDir>/.last-run.json. The output directory is configured by your Playwright setup, so inspect playwright.config.ts if the file is not where expected.

Override the location for one command:

npx playwright test --last-failed --last-failed-file=/tmp/playwright-last-run.json

Or configure the environment variable for a job:

PLAYWRIGHT_LAST_RUN_OUTPUT_FILE=/tmp/playwright-last-run.json npx playwright test --last-failed

In CI, publish this file as an artifact when a later job or developer workstation must replay the same failures. The file must come from the run whose failures you intend to select, and the tests must remain discoverable under the same project and configuration.

Previous-run selection versus automatic retries

Need	Use	When selection happens
Replay failures after a run ended	`--last-failed`	At the start of a new command
Retry an intermittent failure immediately	`--retries=N` or `retries`	During the current command

Retries are disabled by default. Enable them from the CLI:

npx playwright test --retries=2

Or in playwright.config.ts:

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

export default defineConfig({
  retries: 2,
});

Playwright reports a test as passed when its first attempt passes, flaky when it fails and then passes on retry, and failed when all attempts fail. A retry that passes is evidence of flakiness; it does not prove the defect is fixed.

Worker and setup behavior during retries

When a test fails, Playwright discards the worker process and browser. A retry starts in a new worker, so beforeAll setup runs again. Make fixtures, setup, and cleanup safe to repeat; do not depend on state left in a crashed worker.

Keep evidence for failed and retried tests

Traces make a rerun useful for diagnosis. Configure trace retention for the first retry or for failures:

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

export default defineConfig({
  use: {
    trace: 'on-first-retry',
    // Alternatives include 'retain-on-failure'
    // and 'retain-on-failure-and-retries'.
  },
  retries: 2,
});

Use on-first-retry when you want a trace only when a retry is needed. Retain modes preserve more evidence when the original failure and retry both matter. Open a saved trace with:

npx playwright show-trace path/to/trace.zip

A reliable CI workflow

Run the suite with an intentional retry count and trace policy.
Store the report, traces, and .last-run.json as artifacts.
Restore the artifact in a follow-up job and run npx playwright test --last-failed --last-failed-file=....
Run selected failures without retries when you need a clear pass/fail signal, then investigate tests that pass only with retries.

Playwright recommends one worker in CI for stability and reproducibility. On powerful self-hosted CI, parallel workers can help; sharding distributes tests across jobs. Keep the last-run file associated with the shard that produced it so one shard does not overwrite another shard’s selection.

Retry strategy option

Current Playwright configuration documentation lists retryStrategy as available since v1.62. immediate retries when a worker is available (the documented default). isolated waits and runs retries later, one at a time in one worker, trading longer runtime for less interference. Check your installed Playwright version before using it.

Troubleshooting

“No tests found” or no tests are selected

Cause: the last-run file is missing, was overwritten, or points to tests that are not discoverable under the current config.
Fix: restore the file from the original artifact, verify outputDir, use --last-failed-file, and confirm the same project, grep filters, and test paths.

The command reruns a different set than expected

Cause: a newer run replaced .last-run.json, or parallel CI jobs shared one output directory.
Fix: give each job or shard a separate output directory and archive a uniquely named last-run file.

A test passes with retries but fails later

Cause: the test is flaky. Timing races, shared state, network dependencies, and non-repeatable setup are common causes.
Fix: inspect the original and retry traces, wait on meaningful UI conditions, remove ordering dependencies, and make fixtures idempotent.

Retry setup behaves differently

Cause: the failed worker and browser were discarded, so worker-scoped state and beforeAll setup ran again.
Fix: recreate required state in setup and clean it up safely on every attempt.

The last-run file is unavailable in a later CI job

Cause: it was not uploaded as an artifact, or it was restored to another path.
Fix: publish it from the producing job and pass its restored absolute path to --last-failed-file.

Performance, reliability, and cost

Fast feedback: --last-failed skips tests that already passed.
Reproducibility: preserve the matching Playwright version, config, browser binaries, environment variables, and last-run file.
Parallelism: one CI worker favors stable reproduction; more workers and sharding shorten wall-clock time but can expose shared-state problems.
Retry cost: retries multiply browser, fixture, and external-service work. Use the smallest count that gives useful evidence.
Artifact cost: traces and videos consume storage. Retain them for failures or first retries when full retention is unnecessary.

Or skip the browser setup

If your goal is a clean image of a page involved in a test or debugging report, ScreenshotNeo provides one HTTP request instead of capture code. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

See the ScreenshotNeo API documentation for full-page and element capture, device and viewport settings, waits, custom headers and cookies, blocking rules, caching, async jobs, and bulk capture.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does `--last-failed` enable retries?

No. It selects failures recorded by an earlier run. Configure --retries separately for within-run retries.

Can I choose the record file?

Yes. Use --last-failed-file or PLAYWRIGHT_LAST_RUN_OUTPUT_FILE.

Should CI always use one worker?

Playwright recommends one worker for stability and reproducibility. Add workers or sharding when your environment isolates state and needs shorter wall-clock time.

What does a retry-passing test mean?

Playwright classifies it as flaky. Keep the trace and investigate the cause instead of treating the retry as a permanent fix.