Playwright Metadata Validator

A TypeScript library that provides validation for Playwright test metadata including tags and annotations. This library helps ensure consistent and valid metadata across your Playwright test suite, with built-in support for JUnit reporting integration.

Features

• ✅ Tag Validation: Validates Playwright test tags against predefined valid tags
• ✅ Annotation Validation: Validates test annotations with type-safe descriptions
• ✅ TypeScript Support: Full TypeScript support with comprehensive type definitions
• ✅ CLI Tool: Command-line interface for validation in CI/CD pipelines
• ✅ Script Execution: Integrate validation through yarn/npm scripts
• ✅ Configurable: Flexible configuration options for different environments
• ✅ Comprehensive Testing: Extensive test suite with 132+ tests

Usage: CLI for CI/CD Pipelines

Use the CLI tool in your CI/CD linting pipelines to catch metadata validation errors early in the development process, before tests are executed.

The CLI tool provides fast, lightweight validation that integrates seamlessly with your existing linting and code quality checks.

# Add to your CI/CD pipeline (package.json scripts)
{
  "scripts": {
    "validate:metadata": "playwright-meta-validator --fail-on-error",
    "lint": "eslint . && playwright-meta-validator --fail-on-error"
  }
}

Installation

npm install playwright-meta-schema
# or
yarn add playwright-meta-schema

Quick Start

Add metadata validation to your CI/CD pipeline:

# Install the package
npm install playwright-meta-schema
# or
yarn add playwright-meta-schema

# Add to package.json scripts
{
  "scripts": {
    "validate:metadata": "playwright-meta-validator --fail-on-error --verbose",
    "lint": "eslint . && playwright-meta-validator --fail-on-error"
  }
}

# Run in your CI pipeline
npm run validate:metadata
# or
yarn validate:metadata

Valid Tags

Playwright Built-in Tags

• @skip - Skip the test
• @fail - Mark test as expected to fail
• @fixme - Mark test as needing fixes
• @slow - Mark test as slow
• @fast - Mark test as fast

Custom Tags

• @smoke - Smoke tests
• @regression - Regression tests
• @sanity - Sanity tests
• @e2e - End-to-end tests

Valid Annotations

Importance

await test.info().annotate({ type: 'importance', description: 'critical' });
await test.info().annotate({ type: 'importance', description: 'high' });
await test.info().annotate({ type: 'importance', description: 'medium' });
await test.info().annotate({ type: 'importance', description: 'low' });

Interface Type

await test.info().annotate({ type: 'interface', description: 'ui' });
await test.info().annotate({ type: 'interface', description: 'api' });
await test.info().annotate({ type: 'interface', description: 'cli' });
await test.info().annotate({ type: 'interface', description: 'db' });

Test Category

await test.info().annotate({ type: 'category', description: 'unit' });
await test.info().annotate({ type: 'category', description: 'function' });
await test.info().annotate({ type: 'category', description: 'system' });
await test.info().annotate({ type: 'category', description: 'integration' });
await test.info().annotate({ type: 'category', description: 'performance' });

Links and Assignees

await test.info().annotate({
  type: 'link',
  description: 'https://jira.example.com/TICKET-123',
});
await test
  .info()
  .annotate({ type: 'assignee', description: '[email protected]' });

CLI Usage

# Basic validation (demo mode - shows examples)
npx playwright-meta-validator

# Fail on validation errors (recommended for CI)
npx playwright-meta-validator --fail-on-error

# Verbose output for debugging
npx playwright-meta-validator --verbose --fail-on-error

# With custom configuration file
npx playwright-meta-validator --config ./metadata-config.json --fail-on-error

CI/CD Integration Examples

# GitHub Actions example
- name: Validate Playwright Metadata
  run: yarn validate:metadata

# GitLab CI example
lint:metadata:
  script:
    - yarn validate:metadata

Package.json Script Integration

{
  "scripts": {
    "validate:metadata": "playwright-meta-validator --fail-on-error",
    "lint": "eslint . && yarn validate:metadata",
    "ci": "yarn lint && yarn test"
  }
}

Example: content-sources-frontend Integration

The content-sources-frontend project demonstrates how to integrate this validation tool:

{
  "scripts": {
    "validate:metadata": "playwright-meta-validator --fail-on-error"
  }
}

This script can be run locally during development or as part of your CI/CD pipeline to ensure all test metadata is valid before tests execute.

Development

# Install dependencies
yarn install

# Build the project
yarn build

# Run tests
yarn test

# Run tests with coverage
yarn test:coverage

# Lint and format code
yarn lint

# Test CLI functionality
yarn validate:playwright

# Run CLI with different options
npx playwright-meta-validator --verbose
npx playwright-meta-validator --fail-on-error

Recommended Workflow

1. Development: Use CLI tool locally to validate metadata

   yarn validate:metadata

2. CI/CD Pipeline: Integrate CLI validation as a linting step

   yarn lint  # includes validate:metadata

3. Pre-commit Hooks: Optionally add validation to pre-commit hooks for early feedback

Versioning

This project follows Semantic Versioning. The version is determined by Git tags, not by the package.json version field.

Releases

Releases are fully automated through GitHub Actions. To release a new version:

1. Create a new release in GitHub with a tag in the format vX.Y.Z (e.g., v1.0.0)
2. The CI workflow will automatically publish to npm with the version from the tag
3. No code changes or commits are needed to update the version

See RELEASE.md for detailed release instructions.

Contributing