6.8 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: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
The npm installer has not been released. These are future release requirements, not completed test results:
- 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.
- Check that the frontend, Harness, reference material, and presets are complete. Verify service readiness separately from model configuration.
- Test ordinary conversations and AI colleague 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.
- 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.
- 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.
- 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
- For a bug fix, first provide a reproduction that fails.
- Run the affected tests and identify any environment-dependent checks you did not run.
- For changes across packages, verify their integration with a real database or host.
- Check user-facing interactions in a browser, including waiting, failure, and recovery.
- 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.
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.