playwright-requirements

Visualize Playwright tests as product requirements

Transform your Playwright test suite into a beautiful, readable requirements document. See your test coverage as a living specification — organized by project, file, and describe block with health metrics.

Features

• Hierarchical View — Projects > Files > Describe blocks > Tests, with proper nesting
• Status Indicators — active / skip / fixme / slow with distinct icons and colors
• Health Metrics — Coverage percentage with visual health bar
• Multiple Formats — Terminal (ANSI), Markdown (GitHub-ready), JSON (programmatic)
• Filtering — By @tag or project name
• Zero Config — Works out of the box with any Playwright project

Requirements

• Node.js >= 18
• @playwright/test installed in your project

Installation

# Global
npm install -g playwright-requirements

# Per project
npm install -D playwright-requirements

# pnpm
pnpm add -D playwright-requirements

Usage

CLI

# Terminal output (default)
npx playwright-requirements

# Short alias
npx pw-req

# Markdown output
npx pw-req --format markdown

# JSON output
npx pw-req --format json

# Save to file
npx pw-req --format markdown --output requirements.md

# Filter by tag
npx pw-req --tag @smoke

# Filter by project
npx pw-req --project chromium

# Custom Playwright config path
npx pw-req --config path/to/playwright.config.ts

# Disable colors
npx pw-req --no-color

CLI Options

Option	Alias	Description	Default
--format	-f	Output format: terminal, markdown, json	terminal
--tag	-t	Filter by tag (e.g., @smoke)	—
--project	-p	Filter by project name	—
--output	-o	Write to file instead of stdout	stdout
--no-color	—	Disable ANSI colored output	false
--config	-c	Path to Playwright config file	auto-detect

Programmatic API

import {
  parsePlaywrightJSON,
  filterByTag,
  filterByProject,
  formatTerminal,
  formatMarkdown,
  formatJSON,
} from 'playwright-requirements'

// Parse Playwright JSON reporter output
const requirements = parsePlaywrightJSON(playwrightJsonOutput)

// Filter
const smokeTests = filterByTag(requirements, '@smoke')
const chromiumOnly = filterByProject(requirements, 'chromium')

// Format
console.log(formatTerminal(requirements))       // ANSI colored
console.log(formatTerminal(requirements, true))  // No color
console.log(formatMarkdown(requirements))        // GitHub Markdown
console.log(formatJSON(requirements))            // Pretty JSON
console.log(formatJSON(requirements, false))     // Compact JSON

Output Examples

Terminal

╭──────────────────────────────────────────────────────────╮
│  📋 REQUIREMENTS          playwright-requirements        │
╰──────────────────────────────────────────────────────────╯

[chromium]  50 tests
────────────────────────────────────────────────────────

  📁 auth.spec.ts

    ▸ authentication journeys  (4 tests)
      ✓ redirects guest from protected timeline route
      ✓ logs in with seed credentials and signs out
      ✓ FR-028 username validation rejects short input
      ✓ FR-029 password validation rejects short input

  📁 security.spec.ts

    ▸ security hardening  (8 tests)
      ✓ FR-037 rate limit threshold coverage
      ✓ FR-038 secure session cookie attributes
      ✓ FR-039 CSRF rejection matrix
      ✓ FR-040 XSS payload matrix
      ✓ FR-041 SQL injection safety matrix
      ✓ FR-042 foreign key and cascade behavior
      ✓ FR-043 transactional atomicity rollback
      ✓ FR-044 uniqueness constraints matrix

╭──────────────────────────────────────────────────────────╮
│  Total: 50  ✓ 50  ⊘ 0  ✗ 0  Health: 100%                 │
│  ████████████████████                                    │
╰──────────────────────────────────────────────────────────╯

Markdown

# Requirements

## Summary

| Total | Active | Skip | Fixme | Health |
|-------|--------|------|-------|--------|
| 50    | 50     | 0    | 0     | 🟢 100% |

## [chromium] (50 tests)

### 📁 auth.spec.ts

#### authentication journeys (4 tests)

- ✅ redirects guest from protected timeline route
- ✅ logs in with seed credentials and signs out
- ✅ FR-028 username validation rejects short input
- ✅ FR-029 password validation rejects short input

Status Icons

Status	Terminal	Markdown	Meaning
active	✓ (green)	✅	Test runs and passes
skip	⊘ (gray)	⏭️	Test is skipped
fixme	✗ (red)	🔴	Test is marked fixme
slow	⏱ (yellow)	⏱️	Test is marked slow

How It Works

playwright-requirements runs npx playwright test --reporter=json --list under the hood, which lists all tests without executing them. The JSON output is then parsed into a hierarchical tree (Project > File > Describe > Test) with status annotations (skip, fixme, slow) and formatted into your chosen output.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT © Ryota Murakami