This documentation is available as Markdown. For the complete index, see llms.txt. Skip to content
unotest

Overview

For the complete documentation index, see llms.txt
View Markdown Open in ChatGPT Open in Claude

A box is a hosted unotest installation for one organisation. It runs the same viewer you use locally, in front of your own environments, and adds what a team needs around it: sign-in with your identity provider, roles, seats, an audit trail, scheduled runs and a place for CI to push suites to.

Your tests never leave your repository except by your own action: a box holds no credential to your code and never pulls anything. Suites reach it through bundle push.

What is inside

ComponentWhat it does
GuardSign-in, roles, seats, the licence check, the administration pages and the audit trail. Every request to the box passes through it.
ViewerOne viewer per environment, in a container of its own. The same UI as npx @unotest/web viewer, with the controls your role does not permit greyed out. It sees the environment’s bundle and run history and nothing else of the box.
Run sidecarThe only component that holds the docker socket. Every run — ordered from the viewer, from CI, or by a schedule — and every bundle’s npm ci executes in a throwaway container it starts for that one job.
DaemonStores pushed bundles, holds each environment’s values and secrets, runs the per-environment queue and the schedules, and answers CI. It executes none of your code: it asks the sidecar for a container.
UpdaterKeeps the box on the stable release channel, verifying every artifact before it is installed and rolling back if the stack does not come up healthy.

Projects and environments

A box serves one or more projects, each with one or more environments (test, staging, prod, …). An environment has a target — the URL the tests run against, injected into every run as APP_BASE_URL — plus its own variables, secrets, run history, queue and viewer. Which environments exist is decided in the box’s configuration, which unotest maintains with you; a pushed suite cannot create or rename one.

Pull requests can get environments of their own (pr-<n>), created and removed automatically when a project has preview deployments — see Pushing suites.

Where your code runs

Nothing of your suite executes next to the box’s own state. A run gets a container of its own: the bundle’s files read-only, the environment’s run history read-write, the target, variables and secrets of that one environment — and no view of the daemon, of other environments, of tokens or of channel credentials. The container is gone when the run is over. A bundle’s npm ci runs the same way, so a dependency’s install script builds a native module without touching the box. The viewer of an environment is a long-lived container on a network shared only with the guard and the daemon, with no route out of the box.

Two consequences for the UI on a box: editing a suite’s files is not available — the sources are read-only there, and a push is what changes them (such edits never survived the next bundle push anyway) — and Debug cannot attach to a run, which lives in a container the viewer has no path into. Details in Security model.

What you receive

When unotest provisions a box for you:

  • A domain — https://tests.example.com, or a name under your own domain. Sign-in redirects, the CI webhook and the viewer all live there.
  • A licence — signed, with your organisation’s name, a seat count and an expiry date. Seats are counted against people who have signed in recently; see Sign-in.
  • Project tokens — for bundle push and CI, one per project. Tokens that may also write environment values are minted separately.

You provide the identity-provider details (an OAuth client, and for Google Workspace a directory service account) and the mapping from your groups to roles. Nothing about your Workspace is stored anywhere but on your box.

Roles

Two roles exist:

  • admin — run tests, open the terminal, switch an environment’s bundle, administer users, see and set environment values.
  • readonly — browse scenarios, runs and results. Run and the terminal are unavailable, and the proxy refuses them regardless of what the UI shows.

Roles come from your directory groups, and an administrator can pin one on the box. Details in Sign-in and Administration.

Next