Testing

Parallax Designer uses layered tests to protect behavior that is easy to break and hard to catch manually.

Why These Tests Exist

The test strategy is intentionally risk-driven:

• keep core logic regressions out of production (schema, presets, export formatting)
• protect cross-module behavior that manual QA misses (useProjectIO, useLayerAssets, state mutation flows)
• validate only critical end-user browser journeys with E2E (not exhaustive UI permutations)

This avoids shallow “test for coverage only” suites and keeps maintenance cost proportional to risk.

Current Test Layers

Unit

Unit tests focus on pure logic with no Vue runtime mounting.

Current unit scope:

• schema validation and normalization
• project defaults and preset application behavior
• export payload generation
• numeric constraint clamping
• background CSS composition
• local asset reference parsing

Integration (Phase One)

Integration tests focus on composable boundaries and local persistence behavior:

• useProjectState layer mutation and ordering invariants
• useProjectIO import/preset flows
• useLayerAssets upload/delete/resolve behavior with IndexedDB

E2E (Phase Two)

Playwright covers critical browser-level journeys only:

• panel toggle via keyboard shortcut (H)
• layer lifecycle smoke (add, duplicate, visibility, delete)
• preset apply confirmation and undo action flow
• JSON import modal (invalid + valid paste path)
• export guard when layer count is below minimum
• clear local data confirmation and starter reset flow

These are the minimum browser-level checks that exercise real user-critical outcomes.

Testing Philosophy

Tests should validate behavior and invariants, not just implementation details.

A useful unit test in this project should:

• assert a real product rule (for example, layer trimming at max layer count)
• fail if behavior regresses in production
• avoid brittle assertions tied to incidental formatting or ordering

Run Tests

Unit tests:

npm run test:unit

Unit watch mode:

npm run test:unit:watch

Integration tests:

npm run test:integration

Integration watch mode:

npm run test:integration:watch

E2E tests:

npm run test:e2e

E2E in headed mode:

npm run test:e2e:headed

Default test alias (currently unit only):

npm test

CI Status

Current GitHub Pages deploy workflow runs npm run check (i18n + docs sync + type-check), then builds app + docs.

Test commands are available and documented, but merge/deploy gating for tests is still pending CI policy decisions.

Test Layout

Tests are stored under:

tests/

Current layout:

tests/unit/core/
tests/integration/
tests/e2e/

Coverage Goals (Practical)

Coverage percentage alone is not the goal. Prioritize tests that lock down:

• schema compatibility and normalization safety
• preset behavior across replace and keep strategies
• export correctness for JSON/runtime HTML outputs
• deterministic helper behavior used across the app
• composable + persistence boundaries that span multiple modules

Add a New Unit Test

1. Identify a user-visible rule or invariant.
2. Write a test that fails without the intended behavior.
3. Keep fixtures small and explicit.
4. Assert outcomes, not internal implementation noise.

Related Commands

• npm run check:i18n validates translation key parity.
• npm run typecheck runs TypeScript + Vue SFC type checks.
• npm run build builds the app bundle.
• npm run check:docs-sync validates documentation/source synchronization checks.
• npm run check runs i18n + docs-sync + type-check validation.
• npm run verify runs check + unit/integration tests + app/docs builds.