Lab manifest reference

Start with the complete own-app lab and use this reference when changing its source, route, or execution controls.

Where labs live

Labs are authored as .yaml source:

humanish/labs/*.yaml          committed public-safe labs
.humanish/labs/*.yaml         ignored local labs
.humanish/local/labs/*.yaml   ignored private or machine-specific labs

Committed labs should be useful to anyone who clones the project. Private repo targets, token-backed provider settings, and local-only dogfood variants belong in ignored .humanish/ lab manifests and can be run explicitly:

npx humanish watch .humanish/labs/local-dogfood.yaml --env-file .humanish/local/provider.env
npx humanish lab run .humanish/labs/local-dogfood.yaml --json --no-open

--env-file loads values into the current Humanish process; declared subject variables can then be provisioned to the sandbox. Environment provenance records names. Persisted text is scrubbed for known values and secret patterns, with the coverage limits described in the privacy guide.

Inspect the route before running

npx humanish lab list --json
npx humanish lab inspect first-run --json
npx humanish lab preflight first-run --json

A lab's subject, execution target, actor, and scenario jointly determine its route. Declaring a field does not make every route support it. Read preflight warnings; unsupported compositions fail closed or identify inert fields.

In Humanish 0.83.0 and later, lane and roster-group objects reject unknown fields before a run starts. For example, runtme produces HUMANISH_LAB_INVALID with the group or lane index; it cannot silently become a default lane. Use instruction for a lane's steer.

Computer-use controls cover hosted browsers, screenshots, devices, stopping, and reruns. For the complete schema and route validation, read the lab parser and schema contracts.

Scripted browser scenarios

humanish run --app-url http://127.0.0.1:3000 looks for executable browser steps in committed humanish/scenarios/*.yaml. If none are present, Humanish falls back to the built-in two-step browser persona proof. Browser steps are public-safe source, so use synthetic fixture values and committed relative app paths only.

schema: humanish.scenario.v1
id: todo-onboarding
title: Todo onboarding
persona: synthetic-new-user
goal: Create the first synthetic todo and verify the list updates.
mode: browser
browser:
  startPath: /
  steps:
    - id: open-home
      label: Open the todo app
      action: goto
      path: /
      expect:
        text: Add todo
    - id: enter-todo
      label: Enter synthetic todo text
      action: fill
      selector: input[name="todo"]
      value: Synthetic onboarding task
    - id: create-todo
      label: Create the todo
      action: click
      selector: button[type="submit"]
      expect:
        text: Synthetic onboarding task
        stateChanged: true

Supported actions are goto, fill, click, assertText, waitForText, and waitForSelector. Supported expectations are text, selectorVisible, urlIncludes, and stateChanged. Generated traces are stored as JSON under .humanish/runs/<run>/traces/ and summarized in the Observer.

Maintainer OSS meta-lab example

This repository includes a contract-only authorized-repo dogfood lab:

pnpm humanish -- lab run oss --dry-run --repos CorentinTh/it-tools,drawdb-io/drawdb,maciekt07/TodoApp,lissy93/dashy

Default lab targets are intentionally app/tool-like repos with visible, locally runnable user surfaces. Avoid libraries and frameworks for public dogfood unless the scenario is explicitly testing developer experience.

The bundled manifest defaults to dry-run and creates contract evidence without cloning repos, launching a provider sandbox, or forwarding credentials. Use:

pnpm humanish -- lab run oss --dry-run --json --no-open

Live OSS meta-lab execution is unavailable until repository-derived instructions have an isolated credential boundary. A live manifest fails closed with HUMANISH_OSS_META_LIVE_ISOLATION_REQUIRED before callbacks, filesystem writes, network access, or provider launch.

The oss lab accepts GitHub owner/repo slugs. A CLI --repos override redacts repo labels in durable artifacts by default; pass --no-redact-repos only for a public-safe selection. Dry-run does not access or clone repositories and does not need or use private-repository credentials. Private-repository execution remains unavailable while the live lane is disabled. Local bundles remain ignored under .humanish/; do not publish private screenshots, logs, or upstream details.