Skip to content
ContractSpec
Start here

Package manual · examples

·Examples and implementation patterns

example.harness-lab

Focused harness example for ContractSpec scenarios, suites, orchestration, and runtime adapters.

examplesexamplev5.0.4stablewebbrowser
@lssm-tech/example.harness-lab
bun add @lssm-tech/example.harness-lab
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

Focused harness example for scenario contracts, suites, orchestration, and real runtime adapters.

What This Demonstrates

  • Contract layer: canonical harness-scenario and harness-suite exports.
  • Orchestration layer: HarnessRunner, HarnessEvaluationRunner, and replay bundle generation.
  • Runtime layer: SandboxedCodeExecutionAdapter, PlaywrightBrowserHarnessAdapter, optional AgentBrowserHarnessAdapter, DefaultHarnessTargetResolver, and InMemoryHarnessArtifactStore.
  • A deterministic local browser fixture that stays offline and exercises Playwright, auth profile refs, visual diff evidence, and optional agent-browser evidence.
  • src/docs/ contains docblocks and documentation-facing exports.

Running Locally

From examples/harness-lab:

  • bunx playwright install chromium
  • bun run build
  • bun run test
  • bun run typecheck

Sandbox Provider

Pass an IsolatedCodeSandboxPort as sandbox to runHarnessLabSandboxEvaluation({ sandbox }) or createHarnessLabEvaluationTools({ sandbox }). Without a provider, code execution is blocked. Choose a container, process, or remote provider with isolation suitable for your workload. The tests execute only the checked-in fixture scripts in a separate process; that fixture is not a sandbox for untrusted code.

Usage

Use @lssm-tech/example.harness-lab as the focused harness reference package. It pairs with @lssm-tech/example.agent-console, which remains the business-oriented proof example for harness contracts.

Architecture

  • src/docs/ contains docblocks and documentation-facing exports.
  • src/example.ts is the runnable example entrypoint.
  • src/harness-lab.feature.ts defines the feature entrypoint for docs/discovery.
  • src/index.ts is the root public barrel and package entrypoint.
  • src/runtime/ contains the runnable sandbox and browser evaluation helpers plus the local browser fixture.
  • src/scenarios/ contains sandbox, Playwright browser, authenticated browser, visual baseline, and optional agent-browser scenario contracts.
  • src/suite/ contains the dual-mode harness suite contract.

Public Entry Points

  • Export . resolves through ./src/index.ts.
  • Export ./docs resolves through ./src/docs/index.ts.
  • Export ./docs/harness-lab.docblock is an alias of ./docs and resolves through ./src/docs/index.ts.
  • Export ./example resolves through ./src/example.ts.
  • Export ./harness-lab.feature resolves through ./src/harness-lab.feature.ts.
  • Export ./runtime resolves through ./src/runtime/index.ts.
  • Export ./runtime/runAgentBrowserEvaluation resolves through ./src/runtime/runAgentBrowserEvaluation.ts.
  • Export ./runtime/runAuthenticatedBrowserEvaluation resolves through ./src/runtime/runAuthenticatedBrowserEvaluation.ts.
  • Export ./runtime/runBrowserEvaluation resolves through ./src/runtime/runBrowserEvaluation.ts.
  • Export ./runtime/runSandboxEvaluation resolves through ./src/runtime/runSandboxEvaluation.ts.
  • Export ./runtime/runVisualEvaluation resolves through ./src/runtime/runVisualEvaluation.ts.
  • Export ./scenarios resolves through ./src/scenarios/index.ts.
  • Export ./scenarios/harnessLabAgentBrowser.scenario resolves through ./src/scenarios/harnessLabAgentBrowser.scenario.ts.
  • Export ./scenarios/harnessLabAuthenticatedBrowser.scenario resolves through ./src/scenarios/harnessLabAuthenticatedBrowser.scenario.ts.
  • Export ./scenarios/harnessLabBrowser.scenario resolves through ./src/scenarios/harnessLabBrowser.scenario.ts.
  • Export ./scenarios/harnessLabSandbox.scenario resolves through ./src/scenarios/harnessLabSandbox.scenario.ts.
  • Export ./scenarios/harnessLabVisual.scenario resolves through ./src/scenarios/harnessLabVisual.scenario.ts.
  • Export ./suite resolves through ./src/suite/index.ts.
  • The package publishes 21 total export subpaths; keep docs aligned with package.json.

Local Commands

  • bun run dev — contractspec-bun-build dev
  • bun run build — contractspec-bun-build build
  • bun run test — bun test
  • bun run lint — bun lint:fix
  • bun run lint:check — biome check .
  • bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
  • bun run typecheck — tsgo --noEmit
  • bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
  • bun run publish:pkg:canary — bun publish:pkg --tag canary
  • bun run clean — rimraf dist .turbo
  • bun run build:bundle — contractspec-bun-build transpile
  • bun run build:types — contractspec-bun-build types
  • bun run prebuild — contractspec-bun-build prebuild

Notes

  • Browser tests use a real local Playwright run against an in-package HTTP fixture. Install Chromium locally before running bun run test.
  • Agent-browser tests are optional and skip automatically when the agent-browser CLI is unavailable.
  • Authenticated scenarios use named auth profile refs; storage state is created by the test harness and credentials are not embedded in scenario specs.

Relationships

THIS PACKAGEexample.harness-lab21 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

3 declarations

Declared capabilities

This manifest does not declare a capability catalogue. Use the guide, import map and source to assess the package.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../scripts/biome.cjs check --write .
  • lint:checknode ../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit