Testing

Puzzle uses several test runners depending on the package and the type of behavior being tested.

The repository includes:

• Vitest for unit and component tests.
• Node's test runner for several server-side packages.
• Playwright-backed browser tests through Vitest.
• Docker Compose for MongoDB integration tests.

Install dependenciesCopy Anchor Link

From the repository root:

bun install

Run the repository test commandCopy Anchor Link

The root test script builds the packages first, runs package test scripts, runs the project generator tests, and runs the UI browser tests.

bun run vitest

This is the broadest standard test command in the repository.

Package-specific testsCopy Anchor Link

UI componentsCopy Anchor Link

Run unit and component tests:

bun run --filter "@puzzle-ui/ui" vitest

Run only unit tests:

bun run --filter "@puzzle-ui/ui" test:unit

Run only component tests:

bun run --filter "@puzzle-ui/ui" test:component

Run browser tests:

bun run --filter "@puzzle-ui/ui" test:browser

PiecesCopy Anchor Link

bun run --filter "@puzzle-ui/pieces" vitest
bun run --filter "@puzzle-ui/pieces" test:browser

Project generatorCopy Anchor Link

bun run --filter "@puzzle-ui/create" test

Fullstack authenticationCopy Anchor Link

Run server-side and unit tests:

bun run --filter "@puzzle-ui/fullstack" test

Run browser tests:

bun run --filter "@puzzle-ui/fullstack" test:browser

Authentication and storageCopy Anchor Link

Several backend packages use Node's built-in test runner.

bun run --filter "@puzzle-ui/auth" test
bun run --filter "@puzzle-ui/session" test
bun run --filter "@puzzle-ui/storage" test
bun run --filter "@puzzle-ui/storage-d1" test

MongoDB integration testsCopy Anchor Link

The MongoDB storage adapter uses a dedicated test runner.

bun run --filter "@puzzle-ui/storage-mongodb" test

Docker with Compose must be available. The test script starts its MongoDB test environment and cleans up the container and volume when it finishes.

Type checkingCopy Anchor Link

Run type checks for all packages and the documentation site:

bun run typecheck

Run the documentation site's type check independently:

bun run --filter "@puzzle-ui/site" typecheck

Build checksCopy Anchor Link

Build all packages:

bun run build

Build the documentation site:

bun run --filter "@puzzle-ui/site" build

The site build also validates its MDX pages and documentation examples.

Browser test requirementsCopy Anchor Link

Browser tests require the Playwright Chromium browser to be installed.

If a browser test fails before reaching the test assertions, verify the Playwright browser installation and the local browser dependencies first.

Recommended workflowCopy Anchor Link

For a component change:

1. Run the component's unit tests.
2. Run its component tests.
3. Run its browser tests if keyboard, pointer, focus, or other browser behavior changed.
4. Run the package type check.
5. Build the package.

For a documentation change:

1. Verify all imports and links.
2. Run the site type check.
3. Build the documentation site.

For changes affecting shared packages or public APIs, run the broader repository checks.