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 checkpnpm test:unitpnpm test:e2epnpm 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.tsFor 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
| Concern | Location and reference |
|---|---|
| Business rules and package services | Package src/__tests__/ or existing *.test.ts; use the PGlite test database for storage rules |
| App loaders and actions | apps/web/pages/** server tests or apps/web/lib/ tests; see settings/profile.server.test.ts |
| API handlers | apps/web/tests/routes/; never place tests inside routes/ |
| Browser flows | apps/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
| Symptom | Check |
|---|---|
| New page returns 404 | File is under pages/, the URL omits (app), and the dev server has picked up the new files |
| Page redirects to sign-in | requireSession is doing its job; sign in and retry the return URL |
UI displays app.accountSummary.title | The message key is missing or its namespace does not match |
useForm does not accept your path | Check the companion server file, action export, and ?actionName; regenerate app types or restart development after adding routes |
| Action succeeds but account menu is stale | Loader revalidation does not rerun middleware; redirect when shared user or organization data changes |
/api POST gets 403 | Inspect origin policy and credentials; do not bypass the check to hide the error |
| Organization write gets 409 | The active organization changed after the form rendered; refresh the page in the intended organization |
| Database relation does not exist | Generate, review, and apply the migration against the intended local database |
| Form throws instead of showing an error | Review 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.