renderPage

Render a page in your test process through the worker's own pipeline, and inspect its status, HTML, props, cookies, redirect and cacheability.

import { renderPage } from '@gio.js/core/testing';

const page = await renderPage('/posts/1');

Reference

renderPage(path, options?). path is an absolute path, query string allowed (/posts?page=2).

Returns

A Promise<RenderPageResult>:

Behavior

• On the first call per app directory it discovers your routes, layouts, route.ts handlers, not-found and error files, metadata routes and gio.config.ts plugins (running their onStartup), and loads the project's .env files - never over a variable already set. A route conflict fails the call like it fails the worker's boot.
• getServerSideProps, layouts, notFound(), redirect() and error.tsx files answer exactly as on the server. Nothing is cached between calls.
• Not applied, because the Rust server does them: gio.toml and middleware.ts rules and guards, CSRF checks, rate limits, security headers, the page cache, compression and locale detection. Test those with createTestServer.
• The test runs in production mode unless NODE_ENV=development (vitest sets test): error pages show only a digest, and the message is on the ssr render failed log line.
• With no GIO_SESSION_SECRET in the environment or a .env file, discovery sets a random one for the test process, so session modules load.

Errors

• A method other than GET or HEAD: TypeError.
• A page that answers with an event stream: TypeError - read it with callRoute.
• A path that does not start with /, or one the server would refuse with 400 before any page sees it (a . or .. segment, a stray %): TypeError.
• An invalid cookie name, or a cookie value with ;, CR or LF: TypeError.

Examples

Props, tags and cacheability

For the cached, tagged /posts/[id] page from revalidateTag:

import { expect, it } from 'vitest';
import { renderPage } from '@gio.js/core/testing';

it('renders a cached, tagged post', async () => {
  const page = await renderPage('/posts/1');
  expect(page.status).toBe(200);
  expect(page.props).toEqual({ post: { id: '1', title: 'Hello', slug: 'hello' } });
  expect(page.cacheable).toBe(true);
  expect(page.cacheMaxAge).toBe(60);
  expect(page.cacheTags).toEqual(['posts', 'post:1']);
});

it('404s an unknown post', async () => {
  const page = await renderPage('/posts/999');
  expect(page.status).toBe(404);
  expect(page.props).toBeNull();
});

A redirect and a cookie

For the /dashboard guard from redirect and the /welcome page from Cookie helpers:

it('sends visitors without a session to /login', async () => {
  const page = await renderPage('/dashboard');
  expect(page.status).toBe(302);
  expect(page.redirect).toEqual({ destination: '/login?next=%2Fdashboard', permanent: false });
});

it('greets a returning visitor', async () => {
  const page = await renderPage('/welcome', { cookies: { seen: '1' } });
  expect(page.props).toEqual({ firstVisit: false });
  expect(page.cacheable).toBe(false);   // it read and set cookies
});

Good to know

• Modules are imported once per process. resetTestApp re-runs discovery for added or removed files, but an edit to an imported module shows up only in a new test process.
• Assert on props rather than on HTML text: React separates adjacent text with <!-- --> in server HTML.
• CSS Modules render the server's class names under node:test; under vitest add gioVitest().
• No client bundles are built. The page's bootstrap script points at TEST_ENTRY_SCRIPT (/_gio/testing/entry.js, also exported from @gio.js/core/testing) instead of a real chunk; the hydration envelope that props is read from is the real one.
• Server-only. @gio.js/core/testing imports the server-only marker: a page or component that imports it has its client bundle refused.

Related

• Testing: Pages
• callRoute, createTestServer, resetTestApp
• getServerSideProps

Version history