---
url: /backend/testing.md
description: >-
  Run your API routes through the real stack - routing, middleware, validation,
  error handling - with no network, no server, and no mocks.
---

Backend testing in KosmoJS runs your API routes through the real stack with no network, no running server, and no mocks.

The same in-process dispatch that lets an isomorphic fetch client call your backend during SSR is pointed at your test runner instead.

This is possible because KosmoJS already keeps the client/server boundary as an HTTP call that costs nothing on the server.
Tests reuse that path rather than re-implementing it.

Backend testing can be configured per source folder in `kosmo.config.ts`:

```ts
export default defineConfig({
  backend: {
    // ...
    test: true, // [!code hl]
  },
});
```

Enabled by default; set `test: false` to disable testing entirely.
Or set `test: { seed: false }` to keep the harness and write the files yourself.

## The test option

The option signature is identical on `backend` and `frontend`:

The one difference is where files land. Backend seeding writes a starter `index.test.ts` beside each route in `api/` dir.

### Backend Testing | The test option | TestOption

```ts
export type TestOption = boolean | {
  seed: boolean | {
    // Seed file name; default: index.test.ts
    name?: string;
    // Seed path; default: "api" on backend, "pages" on frontend
    path?: string;
    // Patterns to enable or disable testing on a per-route basis,
    // or to use custom seeding templates for select routes.
    [key: string]: boolean | string | ((r: RouteEntry) => string);
  };

  // Custom Vite settings to use specifically for testing
  viteConfig?: ViteConfig;
};
```

\==

### Backend Testing | The test option | RouteEntry

```ts
export type RouteEntry = {
  // Unique ID across all routes, safe to use as a JavaScript identifier
  id: string;
  // Route name, e.g. "account/[id]"
  name: string;
  // Root folder route defined in; either "api" or "pages"
  folder: string;
  // Path to route file, relative to route folder
  file: string;
};
```

\==

## The seed option

Seeding test files is enabled by default, so `test: true` is shorthand for `{ seed: true }`.
Seeding writes a starter `index.test.ts` file beside each route.

Set `seed: false` to disable seeding and write test files by hand.

```ts [Enable testing but do not seed test files]
export default defineConfig({
  backend: { // or frontend
    test: { // [!code focus:3]
      seed: false,
    },
  },
});
```

Alternatively, provide a map of patterns to seed only specific routes:

```ts
export default defineConfig({
  backend: { // or frontend
    test: { // [!code focus:6]
      seed: {
        // do not seed user routes
        "user/**": false,
      },
    },
  },
});
```

```ts
export default defineConfig({
  backend: { // or frontend
    test: { // [!code focus:7]
      seed: {
        // seed only user routes
        "user/**": true,
        "**": false,
      },
    },
  },
});
```

Also it is possible to use custom templates for seeding by provided a string for value:

```ts
import * as templates from "~/test/templates"; // [!code focus]

export default defineConfig({
  backend: { // or frontend
    test: { // [!code focus:6]
      seed: {
        // use a custom template for user routes
        "user/**": templates.users,
      },
    },
  },
});
```

### `name` and `path`

Two keys inside `seed` are reserved: `name` and `path`.
They control the shape and location of every seeded file.

> Because `seed.name` and `seed.path` are reserved, neither can be used as a pattern key directly.
> To match routes by those names, add a suffix - `"name/*"` or `"name/**"`.

`seed.name` is the seeded file name. By default it is `index.test.ts`, written beside the route it belongs to.
Set `seed.name` to change it - `name: "route.spec.ts"`, for instance, seeds every test file under that name.

`seed.path` is where seeded files land. The default is `api/` on backend and `pages/` on frontend,
which keeps each test file beside its route.

Set `seed.path` to seed them somewhere else. E.g.: `path: "test"` on backend places files in `test/api/<route-name>/`,
and the same option on frontend places them in `test/pages/<route-name>`.

:::info Worth Noting
Changing `seed.name` or `seed.path` after test files have already been seeded does not rename or move the existing files.
They stay where they are, under their original names, and the harness no longer picks them up, since it now looks at the new name/path.
:::

## The harness

`_/test/api` exports `prepareHarness`. Pass it a route name and it returns a client bound to that route.

```ts
import { describe, test } from "vitest";

import { prepareHarness } from "_/test/api";

const { client, clients, route } = await prepareHarness("account");

describe(route, () => {
  test.todo(route);
});
```

`client.<method>` never throws. It returns the `{ body, response }` object so you can assert on payload and status together.
It also never follows redirects - a redirect comes back as a response you can inspect, not as a silent second request.

```ts
const { body, response } = await client.POST([], { json: { some: "data" } });

expect(response.status).toEqual(200);
expect(body).toMatch("...");
```

## Scoped headers

`withHeaders` runs a callback with headers merged over whatever is already in scope.
Use it to test an authenticated subtree without mutating module state.

```ts
import { prepareHarness, withHeaders } from "_/test/api";

const { client, route } = await prepareHarness("account");

test(route, async () => {
  await withHeaders({ authorization: "Bearer test" }, async () => {
    await client.GET();
  });
});
```

`setHeaders` applies headers to every call in the file. `clearHeaders` is the way back.

```ts
import { setHeaders } from "_/test/api";

// For every test in the file.
setHeaders({ authorization: "Bearer test" });

describe("...");
```

## Calling other routes

`prepareHarness` also returns `clients` for the case where an inner route needs to be called alongside the current one.

```ts
import { prepareHarness } from "_/test/api";

const { clients, route } = await prepareHarness("account");

test(route, async () => {
  const { body, response } = await clients["another/route"].GET();
  // ...
});
```

Use `clients` when a test needs to exercise a sibling or nested route without leaving the harness.
The same transport swap applies, so these calls also stay in-process.

## Running tests

A `test` script added to `package.json`, run it using your package manager:

### Backend Testing | Running tests | npm

```sh
npm run test
```

### Backend Testing | Running tests | pnpm

```sh
pnpm test
```

### Backend Testing | Running tests | yarn

```sh
yarn test
```

Vitest accepts path filters, so you can narrow a run to one source folder,
one side of it, or a single route:

```sh
pnpm test <folder>                 # only the given source folder
pnpm test <folder>/api             # only backend routes in that folder
pnpm test <folder>/api/<route>     # only the given backend route
pnpm test <folder>/pages           # only frontend routes in that folder
pnpm test <folder>/pages/<route>   # only the given frontend route
```

:::info Worth Noting
Patterns above works with default [seed.path](#name-and-path) option.
If you set a custom `path`, make sure to include it in the pattern.
E.g.: setting `path: "test"` means the patterns should look like: `<folder>/test/api` and `<folder>/test/pages`.
:::

### Mode

Tests run in `test` mode, so the `.env.test` files are loaded. `--mode` picks another:

```sh
pnpm test --mode stage
```

[Env files ›](/essentials/env-files.md#modes)

### Vitest config

Source folders with testing enabled are loaded as projects into `vitest.config.ts`.

Test files are matched by the `seed.name` and `seed.path` each source folder declares in its [own config](#name-and-path) -
`index.test.ts` beside each route, under `api/` or `pages/`, unless you say otherwise.

```ts [vitest.config.ts]
import { defineConfig, mergeConfig } from "vitest/config";

import { loadConfig } from "@kosmojs/vitest";

export default defineConfig(
  mergeConfig(
    {
      // your config here
    },
    await loadConfig(import.meta.dirname),
  ),
);
```

The file is yours to configure: add more tests, settings, and so on,
just do not remove `loadConfig()`, as that would exclude source folders from the test harness.
