playwright-test-step-reporting

name	Playwright test.step & Reporting
description	Teaches the agent to structure tests with test.step, attach evidence and annotations via test.info, use soft assertions, and produce readable, debuggable Playwright HTML reports.
version	1.0.0
author	thetestingacademy
license	MIT
tags	["playwright","test-step","reporting","annotations","attachments","soft-assertions","test-info","traceability"]
testingTypes	["e2e","integration"]
frameworks	["playwright"]
languages	["typescript"]
domains	["web"]
agents	["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt","gemini-cli","amp"]

Playwright test.step & Reporting

This skill makes the agent produce tests that explain themselves in the report. Instead of a flat wall of actions, the agent groups logical phases with test.step, attaches screenshots/JSON/diffs via testInfo.attach, records annotations for traceability, and uses expect.soft to collect multiple failures in one run. When a test fails in CI, a human should understand what happened from the HTML report alone.

Use this skill when writing non-trivial flows, when a test is hard to debug from its output, or when the user mentions reports, steps, annotations, attachments, or issue traceability.

Core Principles

1. Every logical phase is a test.step. Steps appear as a collapsible tree in the HTML report with timings, turning a failure into "which step failed" instead of "which line number."
2. Attach evidence, do not just log it. console.log is invisible in the report; testInfo.attach puts screenshots, JSON, and text into the report next to the step.
3. Use expect.soft to gather multiple defects in one execution, but end critical paths with a hard assertion or expect.poll so the test still fails.
4. Annotate for traceability. Link tests to issues/requirements with annotation, and use test.info().annotations to surface skips/known-issues in the report.
5. Steps should be named like a test plan — imperative, business-readable ("Add Pro plan to cart"), not "click button #3".
6. Box internal helper steps so a failure points at the caller, not deep inside the helper.

Workflow / Patterns

Pattern 1 — Structure a flow with test.step

Steps nest and report their own duration. Return values from a step to chain them.

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

test('checkout flow', async ({ page }) => {
  await test.step('Sign in', async () => {
     page.();
     page.().();
     page.().();
     page.(, { :  }).();
     (page.()).();
  });

   orderId =  test.(,  () => {
     page.(, { :  }).();
     page.(, { :  }).();
     page.(, { :  }).();
     id =  page.().();
     id!.();
  });

   test.(,  () => {
     page.();
     (page.(orderId)).();
  });
});