Installation and Setup

The testing API is exported by @tantawowa/hosanna-tools; it is not a separate Playwright test project. A project needs Hosanna Tools, a compatible Vitest version, generated application sources, and the configuration that already lets hst run launch the application.

Prerequisites

• The Node.js version required by your Hosanna application. The current hosanna-ui-samples-public engine range requires Node.js 24.17.0 or newer within Node 24.
• npm 11 and the committed package-lock.json in hosanna-ui-samples-public.
• A runnable Hosanna web target.
• Any ignored build-config secret overlays required by the application.
• Chromium installed for the Playwright version bundled with Hosanna Tools.

From a clean checkout, install exactly the locked dependencies:

npm ci

Applications that consume the licensed full-source SDK must also restore the exact hosanna.json pin before generating or launching the app:

npx hst sdk:install

This command requires the application's licensed source key. It refuses to discard edits in an existing app-local SDK; preserve that work before restoring the configured pin. Do not put the key in source, command output, or generated artifacts.

Install the owned Chromium browser in hosanna-ui-samples-public with its checked-in script:

npm run test:ui:install

The script resolves the Playwright version from the project lockfile. On Linux CI workers, npx playwright install --with-deps chromium also installs supported operating-system packages.

Recommended layout

integration/
  __screenshots__/
    web-web/
  fixture.ts
  global-setup.ts
  hosanna-test.config.ts
  smoke/
    launch.test.ts
  support/
vitest.integration.config.ts

Generated output belongs in test-results/ and should be ignored. Approved baselines below integration/__screenshots__/ are source files and should be reviewed and committed.

Configure the Hosanna runtime

The application configuration has three layers:

1. normal Hosanna application/build configuration;
2. HosannaTestConfig, which selects the launch target, ports, artifacts, and preconditions;
3. HS_TEST_PLATFORM and HS_TEST_TARGET, which may select a platform/target for a run.

The test-only buildConfig overlay is merged last for a non-production launch. Use it for non-secret test flags such as remote debugging. The launcher rejects this overlay for prod; do not use it to bypass production configuration.

import { fileURLToPath } from 'node:url';
import { defineHosannaTestConfig } from '@tantawowa/hosanna-tools/testing';

const cwd = fileURLToPath(new URL('../', import.meta.url));

export default defineHosannaTestConfig({
  cwd,
  appName: 'hosanna-ui-samples-public',
  environment: 'dev',
  artifactDirectory: 'test-results',
  timeoutMs: 60_000,
  buildConfig: {
    remoteDebug: {
      isEnabled: true,
      isStartServerByDefault: true,
    },
    mcp: { isEnabled: true },
  },
});

Use unique ports when another Hosanna runtime is likely to be running. The launcher checks the debugger, app, Vite, and browser ports before startup and fails with the occupied port list rather than silently attaching to another run.

Connect Vitest

Global setup owns application launch and teardown. The worker fixture creates a scoped client for each test.

integration/global-setup.ts

import { createHosannaGlobalSetup } from '@tantawowa/hosanna-tools/testing/vitest';
import config from './hosanna-test.config';

export default createHosannaGlobalSetup(config);

integration/fixture.ts

import { createHosannaVitest } from '@tantawowa/hosanna-tools/testing/vitest/fixture';
import config from './hosanna-test.config';

export const { test, expect } = createHosannaVitest(config);

vitest.integration.config.ts

import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vitest/config';
import { createHosannaReporter } from '@tantawowa/hosanna-tools/testing/vitest/reporter';
import config from './integration/hosanna-test.config';

export default defineConfig({
  root: fileURLToPath(new URL('./integration', import.meta.url)),
  test: {
    include: ['**/*.test.ts'],
    globalSetup: ['./global-setup.ts'],
    fileParallelism: false,
    maxWorkers: 1,
    reporters: ['default', createHosannaReporter(config)],
  },
});

A single runtime is shared by the files in the run, so keep file parallelism disabled and use a named precondition to reset state before every test.

Environment variables

The shared launcher understands these general selectors:

Variable	Purpose
HS_TEST_PLATFORM	Hosanna platform such as web or roku
HS_TEST_TARGET	web, sim, or device
HS_TEST_TIMEOUT_MS	Overrides application launch timeout
HS_TEST_DEBUG_HOST	Overrides the LAN host advertised to a Roku
HS_TEST_HEADED	A project convention used by reference configs to set headless: false when 1
HS_TEST_VIDEO	A project convention used by reference configs to disable video when 0
HS_UPDATE_SCREENSHOTS	Creates or replaces visual baselines when 1
HOSANNA_TEST_VERBOSE	Streams owned runtime/browser output when 1

Roku device runs also require the configured device IP and developer password variables. See Devices, Browsers, and Input Methods.

First run

Run the hosanna-ui-samples-public web suite:

npm run test:ui:web

A successful run prints the absolute path to test-results/<testRunId>/report.html and updates test-results/latest.html. Open that file in a browser to confirm the runner, application handshake, and reporter all completed.

After the first run, the sample repository can open the latest report for you:

npm run test:ui:report

Next: Writing and Running Tests.

Reference implementation: hosanna-test.config.ts, global-setup.ts, and vitest.integration.config.ts.