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.
Frontend testing can be configured per source folder in kosmo.config.ts:
export default defineConfig({
frontend: {
// ...
test: true,
},
});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.
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;
};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.
export default defineConfig({
backend: { // or frontend
test: {
seed: false,
},
},
});Alternatively, provide a map of patterns to seed only specific routes:
export default defineConfig({
backend: { // or frontend
test: {
seed: {
// do not seed user routes
"user/**": false,
},
},
},
});export default defineConfig({
backend: { // or frontend
test: {
seed: {
// seed only user routes
"user/**": true,
"**": false,
},
},
},
});Also it is possible to use custom templates for seeding by provided a string for value:
import * as templates from "~/test/templates";
export default defineConfig({
backend: { // or frontend
test: {
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.nameandseed.pathare 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>.
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:
export default defineConfig({
frontend: {
// ...
ssr: true,
test: {
ssr: true,
},
},
});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:
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:
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, withhref()for building its URLpages- every other page, keyed by route nameroute- the route name you passed inbase- 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:
href: (params?: [id: string | number], query?: Record<string, unknown>)Pass a params tuple for dynamic segments, and an optional query object for everything else:
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 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:
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 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:
npm run testVitest accepts path filters, so you can narrow a run to one source folder, one side of it, or a single route:
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 routeWorth Noting
Patterns above works with default seed.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:
pnpm test --mode stageVitest 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 - index.test.ts beside each route, under api/ or pages/, unless you say otherwise.
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.