Automated Testing

MkSaaS uses Vitest for logic and service boundaries, Playwright for browser journeys, and separate Stripe, Creem, and Waffo sandbox suites. Run these commands from your MkSaaS application repository.

Test Coverage

Unit tests replace external services with mocks. Local browser tests use the configured PostgreSQL database; E2E mode skips real mail, signup newsletter subscription, and payment notifications. AI browser tests mock responses. These suites do not establish email delivery, OAuth provider access, or live AI availability.

Prepare the Environment

pnpm install
pnpm e2e:install

For browser and payment tests, configure DATABASE_URL in an uncommitted .env file with a dedicated local or test PostgreSQL database, then apply the template's existing migrations:

pnpm db:migrate

The test runners start their own application servers, but do not provision a database or apply migrations automatically. Fixtures create and clean up e2e-*@example.test users. Use a test database because payment scenarios also write and update payment records.

The ordinary E2E server uses port 3100 and .next-e2e, separate from the template's normal development server on 3000. Production smoke builds into .next-production-e2e and runs next start on port 3201. Keep these ports free; use E2E_PORT or PRODUCTION_E2E_PORT to override them.

Run Tests

pnpm lint:check  # Read-only Biome check
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm check       # lint:check → typecheck → test → build
pnpm e2e

Before releasing a broad template update:

pnpm verify:upgrade  # check → e2e → e2e:production

This validates the local application without deploying. Payment sandbox suites are separate and are not included in verify:upgrade.

To focus on relevant tests:

pnpm test tests/unit/payment
pnpm test:watch
pnpm e2e -- tests/e2e/specs/auth.spec.ts
pnpm e2e -- tests/e2e/specs/ai-playground.spec.ts
pnpm e2e:ui

Payment Sandbox Tests

STRIPE_ENV_FILE=/path/to/sandbox.env pnpm e2e:stripe
CREEM_ENV_FILE=/path/to/sandbox.env pnpm e2e:creem
WAFFO_ENV_FILE=/path/to/sandbox.env pnpm e2e:waffo

# Run one scenario
STRIPE_ENV_FILE=/path/to/sandbox.env pnpm e2e:stripe -- --grep "yearly subscription"

Shell variables override the explicit provider environment file, which overrides project .env* defaults. Use credentials and price/product IDs from the same sandbox account. The launchers force local URLs and E2E fixture settings; they stop their child processes on interruption. Database configuration still needs to point at your test database.

Creem and Waffo runners do not start a tunnel or register webhooks. Point the tunnel at the automated server's port, not your normal dev server. Waffo provides pnpm waffo:setup for separate webhook registration. Port overrides are STRIPE_E2E_PORT, CREEM_E2E_PORT, and WAFFO_E2E_PORT; update the tunnel accordingly. See tests/e2e/<provider>/README.md for complete setup.

Sandbox suites cover selected provider journeys. Unit tests cover additional lifecycle and failure paths; successful sandbox checkout does not prove every renewal, refund, or recovery case.

Maintenance and Troubleshooting

Tests live in tests/unit/ and tests/e2e/. Acceptance journeys are recorded in tests/e2e/TEST-CATALOG.md. Update relevant tests when a functional journey or behavior contract changes. Use stable data-testid selectors for application controls and assert navigation, requests, permissions, and persisted outcomes. Copy, styling, icons, and layout changes alone do not require functional test changes.

Inspect terminal output and test-results/ on failure. Open retained traces with pnpm exec playwright show-trace <trace.zip>. For database errors, check the test database connection and migration history. For pending payments, check webhook delivery, signatures, provider mode, and tunnel connectivity.

Next Steps

Now that you understand how to test your MkSaaS project, explore these related topics: