@lytics/playwright-core

Annotation-driven Playwright testing infrastructure for Lytics and Contentstack

A comprehensive monorepo of Playwright testing tools built around annotation-driven testing - linking tests to user journeys and business requirements for better observability and traceability.

📦 Packages

Public Packages (npm)

Open-source, generic infrastructure for any Playwright project:

Package	Description	Version
@lytics/playwright-annotations	Annotation framework with validation & ESLint
@lytics/playwright-reporter	Adapter-based reporter with pluggable storage
@lytics/playwright-adapters	Storage adapters (filesystem, Slack, Firestore)

Contentstack-Specific Packages

Package	Description	Version
@lytics/playwright-journey	Journey-driven test generation

🚀 Quick Start

Installation

# Public packages (anyone can install)
npm install @lytics/playwright-annotations @lytics/playwright-reporter

# For Lytics/Contentstack teams (requires GitHub auth)
npm install @lytics/playwright-journey

Basic Usage

Step 1: Create a reporter file

// reporter.ts
import { CoreReporter } from "@lytics/playwright-reporter";
import { FilesystemAdapter } from "@lytics/playwright-adapters/filesystem";

class CustomReporter extends CoreReporter {
  constructor() {
    super({
      adapters: [new FilesystemAdapter({ outputDir: './test-results' })]
    });
  }
}

export default CustomReporter;

Step 2: Configure Playwright

// playwright.config.ts
export default {
  reporter: [['list'], ['./reporter.ts']]
};

Step 3: Write annotated tests

// tests/my-feature.spec.ts
import { test } from "@playwright/test";
import { pushSuiteAnnotation, pushTestAnnotations } from "@lytics/playwright-annotations";

test.describe("My Feature @smoke", () => {
  test.beforeEach(async ({}, testInfo) => {
    pushSuiteAnnotation(testInfo, "MY-PRODUCT");
  });

  test("validates user can perform action", async ({}, testInfo) => {
    pushTestAnnotations(testInfo, {
      journeyId: "MY-PRODUCT_FEATURE-CREATE",
      testCaseId: "MY-PRODUCT_FEATURE-CREATE_VALID",
    });

    // Your test implementation...
  });
});

📚 Documentation

• Getting Started Guide
• Annotations Guide
• Adapters Guide
• Release Process
• Journey Guide (Internal)

🏗️ Architecture

Core Concepts

Annotation-Driven Testing: Every test is annotated with metadata linking it to:

• Test Suite - Product/feature area
• Journey - User flow being validated
• Test Case - Specific scenario (valid, invalid, edge case)

Benefits:

• ✅ Traceability (test → journey → requirement)
• ✅ Observability (centralized dashboards)
• ✅ Coverage tracking (which journeys are tested?)
• ✅ Trend analysis (per journey, per suite)

Package Dependencies

annotations (base - no dependencies)
    ↓
reporter (depends on: annotations)
    ↓
adapters (depends on: reporter, annotations)
    ↓
journey (depends on: annotations)

🛠️ Development

Prerequisites

• Node.js (v22 LTS or higher)
• pnpm (v8 or higher)

Setup

# Clone repo
git clone https://github.com/lytics/playwright-core.git
cd playwright-core

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint & format
pnpm lint
pnpm format

Development Workflow

# Watch mode for a specific package
cd packages/annotations
pnpm dev

# Run tests in watch mode
pnpm test:watch

# Type check
pnpm typecheck

Publishing

This monorepo uses Changesets for version management. See RELEASE_PROCESS.md for details.

Quick overview:

1. Make your changes
2. Create a changeset: pnpm changeset
3. Commit and push
4. CI creates a release PR
5. Merge the PR to publish

Public packages publish to npm, internal packages publish to GitHub Packages automatically.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Guidelines

• Use Conventional Commits
• Add tests for new features
• Update documentation
• Run pnpm lint and pnpm format before committing

📄 License

MIT

🙏 Acknowledgments

Built by the Lytics team for better Playwright testing at scale.

Inspired by lessons learned from:

• lytics-playwright
• lytics-e2e-dashboard
• automation-ops

📧 Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions