---
url: /frontend/testing.md
description: >-
  Test pages against a real server - drive a real browser, or assert on
  server-rendered HTML with no browser at all.
---

A frontend test in KosmoJS runs against a real server.
No DOM shim stands in for the page - the test requests a live URL and asserts on what comes back.

It is the same transport trick the backend harness uses, seen from the other end.
The dev server that normally serves your pages is started on a random port for the duration of the run,
and `page.href()` hands you its address.

The dev server renders on the client, so by default a test drives a real browser to see the page.
For a folder with SSR enabled, the harness can serve server-rendered HTML instead,
and a test can assert on it without a browser - see [the ssr option](#the-ssr-option).

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

```ts
export default defineConfig({
  frontend: {
    // ...
    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 has the same shape on `frontend` and `backend`, with seeding on by default once testing is enabled.

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

### Frontend 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;
};
```

\==

### Frontend 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 ssr option

Frontend only. Whether the harness serves an SSR-enabled folder with SSR:

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

Defaults to `false`: the dev server starts much faster,
and a browser renders the same page from either server.

Set it to `true` to assert on the server-rendered HTML itself.
The response is then the full page, so a lightweight parser like Cheerio is enough,
with no browser to install or launch:

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

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

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

describe(route, () => {
  test(route, async () => {
    const $ = load(await fetch(page.href()).then((r) => r.text()));
    expect($("h1").text()).toBe("Account");
  });
});
```

The option has no effect on a folder without SSR enabled.

## The harness

`_/test/pages` exports `prepareHarness`.
Hand it a route name and it returns the pieces a frontend test needs:

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

import { prepareHarness } from "_/test/pages";
import { browser } from "./browser";

const { page, pages, route, base } = await prepareHarness("account");

describe(route, () => {
  test(route, async () => {
    const tab = await browser.newPage();
    await tab.goto(page.href());
  });
});
```

* `page` - the current page, with `href()` for building its URL
* `pages` - every other page, keyed by route name
* `route` - the route name you passed in
* `base` - the origin the harness is serving from

## Navigating with `page.href()`

`href()` is the usual way in. It returns an absolute URL on the harness's origin, typed against the route's own params:

```ts
href: (params?: [id: string | number], query?: Record<string, unknown>)
```

Pass a params tuple for dynamic segments, and an optional query object for everything else:

```ts
const tab = await browser.newPage();
await tab.goto(page.href());
```

The backend harness never gives you a URL, because there is nothing to navigate to.
On frontend, the URL is the whole point -
it carries the port the disposable server is listening on.

## The base property

`base` is the origin requests go to - something like `http://127.0.0.1:20557`.
The port is drawn at random for each run; the host comes from the [kosmo.devHost](/essentials/config.md#project-settings-package-json) key in `package.json`.

You will rarely reach for it directly. `page.href()` already composes `base` with the route's path,
params, and query, and that covers almost every test.

Use `base` yourself only when you need to build a URL the harness does not model -
a static asset, an absolute link, a target outside the route tree.

## Other routes via pages property

`pages` lets a single test touch a page other than the current one, without spinning up a second harness:

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

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

test(route, async () => {
  const tab = await browser.newPage();
  await tab.goto(pages["another/page"].href());
});
```

Same origin, same server, no extra setup.

## What you bring yourself

**The browser.** KosmoJS will not choose one for you. Launch Playwright, Puppeteer,
or whichever driver you prefer in your test setup, and point it at the URLs the harness produces.
The harness owns the server, not the client.
With [ssr](#the-ssr-option) on, a plain `fetch` and an HTML parser may be all you need.

**Header helpers.** `withHeaders`, `setHeaders`, and `clearHeaders` have no frontend counterpart.
In a browser, headers and cookies belong to the browser - set them through the driver's own API,
or carry state through `page.href()`'s query argument.

## Running tests

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

### Frontend Testing | Running tests | npm

```sh
npm run test
```

### Frontend Testing | Running tests | pnpm

```sh
pnpm test
```

### Frontend 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.
