run-tests

name	run-tests
description	Run the test suite for the Cartridge Controller monorepo. Use when validating changes, before committing, or when asked to run tests.

Run Tests

Quick Reference

Command	Purpose	Duration
pnpm lint:check	Lint + format check	~30s
pnpm test	Unit tests	~1-2min
pnpm test:ci	Unit tests with coverage	~2-3min
pnpm test:storybook	Visual regression tests	~5-10min
pnpm build	Full build (includes type check)	~2-3min
pnpm e2e	End-to-end tests	~5-10min

Test Types

1. Linting and Formatting

Fastest check - always run before committing:

pnpm lint:check

This runs:

• ESLint for code quality
• Prettier for formatting

To auto-fix issues:

pnpm format  # Fix formatting + lint

2. Unit Tests

Tests the keychain package:

# Standard run
pnpm test

# With coverage report
pnpm test:ci

# Run specific test file
pnpm keychain test -- --testPathPattern="connection"

Test files are located in:

• packages/keychain/src/**/*.test.ts
• packages/controller/src/__tests__/

3. Storybook Visual Regression Tests

Tests UI components for visual changes:

# Run visual tests (compares against baseline)
pnpm test:storybook

# Update baseline snapshots after intentional changes
pnpm test:storybook:update

Snapshots are stored in:

• packages/keychain/__image_snapshots__/

4. Build (Type Checking)

TypeScript compilation catches type errors:

pnpm build

This also validates that all packages compile correctly.

5. End-to-End Tests

Full integration tests with Playwright:

# Run headless
pnpm e2e

# Run with UI for debugging
pnpm e2e:ui

E2E tests are in:

• examples/next/tests/

CI Equivalence

To mirror what CI runs, execute in order:

# 1. Quality checks (quality.yml)
pnpm lint:check

# 2. Build and test (test.yml)
pnpm build
pnpm test:ci

# 3. Visual regression (test.yml - storybook job)
pnpm test:storybook

Interpreting Results

Test Failures

# Re-run failed test with more details
pnpm keychain test -- --verbose --testNamePattern="failing test name"

Snapshot Failures

If Storybook tests fail with visual differences:

1. Review the diff images in packages/keychain/__image_snapshots__/__diff_output__/
2. If changes are intentional: pnpm test:storybook:update
3. If changes are unintentional: fix the component

Type Errors

# Check specific package
pnpm controller build:deps
pnpm keychain build

Package-Specific Testing

# Controller SDK tests
pnpm controller test

# Keychain tests
pnpm keychain test

# Run test in watch mode for development
pnpm keychain test -- --watch

Common Issues

"Cannot find module" errors

pnpm clean && pnpm i && pnpm build:deps

Storybook tests timeout

Ensure the Storybook server is not already running on port 6006.

E2E tests fail to start

Ensure dev servers are running:

pnpm dev  # In one terminal
pnpm e2e  # In another

Pre-Commit Verification

The git pre-commit hook automatically runs:

pnpm run format --ui stream
pnpm run lint:check --ui stream

This ensures basic quality before every commit.