Testing and Debugging

Verify a feature with type checks, service tests and browser tests, and diagnose routing, auth, forms and database failures.

Verify the behavior you added: a page renders for the right user, the mutation saves, and another user cannot read or change that data. Passing a typecheck alone does not prove those properties.

Checks to Run

From the repository root:

pnpm check
pnpm test:unit
pnpm test:e2e

pnpm check checks formatting, lint, and types without fixing files. pnpm healthcheck runs fixes and the agent-file check, so review its changes. Browser tests use Playwright; see Checks and End-to-End Tests.

For focused unit work, the root test runner accepts a test-file filter:

pnpm exec vp test run apps/web/pages/'(app)'/settings/profile.server.test.ts

For the account summary tutorial, first open /account-summary while signed in. Submit an invalid name, correct it, save, and confirm the new name persists after a reload and appears in the account menu. Try the page while signed out too.

Where Tests Belong

ConcernLocation and reference
Business rules and package servicesPackage src/__tests__/ or existing *.test.ts; use the PGlite test database for storage rules
App loaders and actionsapps/web/pages/** server tests or apps/web/lib/ tests; see settings/profile.server.test.ts
API handlersapps/web/tests/routes/; never place tests inside routes/
Browser flowsapps/e2e/tests/; reuse its page objects and helpers

New app browser specs import test from the kit's tests/utils/test helper, which gives each test its own client IP for rate limits. Reuse the sign-up and hydration helpers rather than relying on a shared demo user or clicking before React is ready.

Cases That Matter

  • The signed-in user can read and change their own data.
  • A signed-out direct request to the action or endpoint is refused.
  • A second user cannot operate on the first user's record, even with its id.
  • Invalid input returns a field error and leaves the form usable.
  • A forbidden role or stale organization tab cannot perform the write.
  • Failure paths do not show a success state or silently substitute empty data.

Database reset and seed commands replace local data. Use a disposable test database or confirm before running them on a development database you care about. Do not run a remote reset as part of a local test.

Common Problems

SymptomCheck
New page returns 404File is under pages/, the URL omits (app), and the dev server has picked up the new files
Page redirects to sign-inrequireSession is doing its job; sign in and retry the return URL
UI displays app.accountSummary.titleThe message key is missing or its namespace does not match
useForm does not accept your pathCheck the companion server file, action export, and ?actionName; regenerate app types or restart development after adding routes
Action succeeds but account menu is staleLoader revalidation does not rerun middleware; redirect when shared user or organization data changes
/api POST gets 403Inspect origin policy and credentials; do not bypass the check to hide the error
Organization write gets 409The active organization changed after the form rendered; refresh the page in the intended organization
Database relation does not existGenerate, review, and apply the migration against the intended local database
Form throws instead of showing an errorReview throwOnError and handle both expected errors and unexpected failures

Logs and Development Email

pnpm kit:doctor reports setup status without changes. When setup started the processes, inspect .makerkit/processes/app.log and .makerkit/processes/database.log locally. The app log includes the development email inbox link; it contains an access key and stays private.

Use the kit's structured logger for application events. Do not log request bodies, credentials, tokens, addresses, or raw database errors containing SQL parameters. Production uses Cloudflare logs and observability; see Operations.

Ready for the Next Feature

Keep the evidence proportional to the change: service tests for rules and ownership, browser coverage for the user flow, and type/lint checks for integration mistakes. The existing Generators, Authorization Policies, and Data Tables guides cover the next layer once the basic page-to-service flow is familiar.