Skip to content

CLAUDE.md

Latest commit

 

History

History
169 lines (124 loc) · 4.05 KB

CLAUDE.md

File metadata and controls

169 lines (124 loc) · 4.05 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Package Management

# Install dependencies
pnpm install

# Add a dependency to a specific package
cd packages/[package-name]
pnpm add [dependency-name]

Build Commands

# Build all packages
pnpm build

# Build a specific package
cd packages/[package-name]
pnpm build

# Build in watch mode (for development)
pnpm dev

# Build a specific package in watch mode
cd packages/[package-name]
pnpm dev

Test Commands

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests for a specific package
cd packages/[package-name]
pnpm test

# Run tests in watch mode for a specific package
cd packages/[package-name]
pnpm test:watch

Linting and Formatting

# Lint all packages
pnpm lint

# Format all packages
pnpm format

# Type check all packages
pnpm typecheck

# Lint a specific package
cd packages/[package-name]
pnpm lint

# Format a specific package
cd packages/[package-name]
pnpm format

# Type check a specific package
cd packages/[package-name]
pnpm typecheck

Version Management

# Create a changeset (for versioning)
pnpm changeset

# Version packages based on changesets
pnpm version

# Publish packages
pnpm release

Code Architecture

This is a TypeScript monorepo for Playwright testing infrastructure based on annotations. It uses pnpm workspaces, Turborepo for build orchestration, and Changesets for versioning.

Package Dependencies

The packages follow this dependency hierarchy:

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

Key Packages

  1. @lytics/playwright-annotations: Base package that provides a framework for annotating Playwright tests with metadata.

    • Defines annotation schema and types
    • Provides validation rules
    • Contains helper functions for working with annotations
    • Includes ESLint integration

  2. @lytics/playwright-reporter: Reporter framework that processes test results with annotations.

    • Builds on top of annotations package
    • Provides a pluggable architecture for different storage backends via adapters
    • Collects and processes test results

  3. @lytics/playwright-adapters: Storage adapters for the reporter.

    • Filesystem adapter for storing results locally
    • Slack adapter for notifications
    • Firestore adapter for Google Cloud Firestore
    • Implements common interfaces for storage backends

  4. @lytics/playwright-journey: Journey-driven test generation.

    • Higher-level abstractions for journey-based testing
    • Connects tests to user journeys and business requirements

Build System

  • Turborepo: Used for task orchestration and caching across packages
  • TypeScript: All packages are written in TypeScript with strict typing
  • Biome: Used for linting and formatting
  • Vitest: Used for unit testing
  • Changesets: Used for versioning and changelogs

Code Conventions

  • Uses strict TypeScript with explicit typing
  • Single quotes for strings
  • 2-space indentation
  • Line width of 100 characters
  • Follows a modular design pattern with clear separation of concerns
  • Uses Conventional Commits for commit messages

Testing Architecture

This codebase implements an annotation-driven testing approach:

  1. Test Suite: Organizational grouping for product or feature area
  2. Journey: User flow being validated
  3. Test Case: Specific scenario (valid, invalid, edge case)

Tests are annotated with metadata using the provided helpers:

// Set suite annotation in test.describe block
pushSuiteAnnotation(testInfo, "MY-PRODUCT");

// Set test annotations in test block
pushTestAnnotations(testInfo, {
  journeyId: "MY-PRODUCT_FEATURE-CREATE",
  testCaseId: "MY-PRODUCT_FEATURE-CREATE_VALID",
});

The reporter processes these annotations and sends them to configured adapters for storage and analysis.