# Testing and Debugging

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/development-guide/testing-and-debugging*

---

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:

```bash
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](../deployment/checks-and-e2e).

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

```bash
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

| 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](./logging) 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](../operations/overview).

## 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](./generators), [Authorization Policies](./authorization-policies), and [Data Tables](./data-tables) guides cover the next layer once the basic page-to-service flow is familiar.
