6.9 Testing and contributing

Identify the boundaries affected by a change before choosing tests. Assertions that simply copy constants from source code do not replace behavioral tests.

Command	Coverage
pnpm test:contract	Shared contracts and parsing
pnpm test:work	Backend business logic and the database
pnpm test:native	DSH adapter and execution authorization
pnpm test:npm	Native installer and distribution resources
pnpm test:bindings	Client bindings and interaction state
pnpm test:references	Read-only MCP service and protocol
pnpm test:prototype	Shared scripts and prototype logic
pnpm typecheck	Build and root type checking
pnpm check:client	Client build boundaries

Choose an environment for the check

Purpose	Recommended environment	What to verify
Daily development and interaction debugging	Native Teloa and Harness with Docker PostgreSQL	Local paths, programs, permissions, and Web behavior
Backend integration and CI builds	Isolated databases or containers, according to test dependencies	Business rules, transactions, initialization, and dependency completeness
npm installation acceptance	A clean target system with the actual distribution package	Independence from source and development caches, local execution, and service lifecycle
Compose deployment regression	Application, Harness, and database in containers	Startup, health checks, persistent volumes, and explicitly mounted files

Passing inside a container does not replace native installation acceptance. A successful shell command in a Linux container does not verify native macOS programs, Windows permissions, or the user's PATH. Record WSL2 and native Windows results separately as well.

npm release acceptance requirements

Changes to the installer still need the checks below, with results recorded per operating system, CPU and Node version.

1. Install the actual npm tarball on a target system without source code, global pnpm, compilers, or existing development caches. After publication, install the same version from the registry.
2. Check that the frontend, Harness, reference material, and presets are complete. Verify service readiness separately from model configuration.
3. Test ordinary conversations and AI employee tasks separately: read and write an authorized local directory, invoke a native program, and verify the resulting files. Also check unauthorized tools, out-of-scope writes, and revoked grants.
4. Cover non-ASCII paths and spaces, read-only directories, missing PATH programs, port conflicts, and repeated or concurrent startup. Check error messages and log redaction.
5. Verify that closing the initiating terminal leaves the service running, stop and restart preserve records, and npm updates or temporary-cache cleanup do not break the running service.
6. Rehearse backup, restore, compatible upgrades, and data retention after uninstall. Restoring must not automatically repeat external actions. Claim support only for tested operating systems, CPUs, and Node versions.

When a change is complete

1. For a bug fix, first provide a reproduction that fails.
2. Run the affected tests and identify any environment-dependent checks you did not run.
3. For changes across packages, verify their integration with a real database or host.
4. Check user-facing interactions in a browser, including waiting, failure, and recovery.
5. Update the documentation, version boundaries, and change records.

Database tests may create containers or temporary schemas. Check the environment and isolation requirements first. Tests using real models incur costs and must not run automatically as ordinary static checks.

Full functional and E2E regression

Install the locked dependencies and run pnpm build first. Database suites use local Docker and run serially under /tmp/teloa-db-test.lock. If the lock exists, identify its owner instead of removing another run's lock. All browsers run headlessly, without using the developer's open pages.

# Point DOCKER_HOST at the Docker socket actually used on this machine.
TELOA_USAGE_STATS=off DOCKER_HOST="unix:///path/to/docker.sock" \
  node tests/system-host-acceptance.mjs

# Rerun affected host scenarios by name.
TELOA_USAGE_STATS=off DOCKER_HOST="unix:///path/to/docker.sock" \
  node tests/system-host-acceptance.mjs model-settings model-fallback

# Website, documentation, marketplace and feedback: local builds and isolated services.
node website/tests/sites-system-e2e.mjs

The host batch creates disposable PostgreSQL, isolated configuration and temporary credentials. It covers onboarding, model selection and fallback, OAuth, extension hot-plugging, tasks, employees, artifacts and group attachments. OAuth includes a real expiry wait of about ten minutes. Results default to .runtime/system-host-acceptance/; set TELOA_SYSTEM_E2E_OUTPUT for a separate run directory. Use SITES_E2E_OUTPUT for the site suite. Inspect individual results, initial failure logs and cleanup results, not just the last output line.

These host tests use deterministic local model and authorization services to verify submission, authorization, persistence and recovery. They do not establish real model quality or production account availability. Actual models, third-party platforms, target hardware and distribution installation require separate acceptance. Preserve skips, known upstream failures and untested environments in the report rather than counting them as passes.

Contribute

Use the source repository's contribution channels to submit a reproducible issue or change, following its CONTRIBUTING.md. Describe the trigger, resulting behavior, test results, and known limitations. Do not include runtime directories, personal photos, credentials, or data unrelated to the change.