---

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

Test Types

1. Linting and Formatting

Fastest check - always run before committing:

Copypnpm lint:check

This runs:

• ESLint for code quality
• Prettier for formatting

To auto-fix issues:

Copypnpm format  # Fix formatting + lint

2. Unit Tests

Tests the keychain package:

Copy# 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:

Copy# 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:

Copypnpm build

This also validates that all packages compile correctly.

5. End-to-End Tests

Full integration tests with Playwright:

Copy# 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:

Copy# 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

Copy# 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

Copy# Check specific package
pnpm controller build
pnpm keychain build

Package-Specific Testing

Copy# 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

Copypnpm 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:

Copypnpm dev  # In one terminal
pnpm e2e  # In another

Pre-Commit Verification

The git pre-commit hook automatically runs:

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

This ensures basic quality before every commit.