---
title: Testing and contributing
description: Choose existing test commands and record results and uncovered areas.
lastVerified: 2026-10-23
---

# 6.13 Testing and contributing

Describe the user behavior affected by your change, then select tests. Run these commands from the Teloa Community source root after preparing [local development](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/local-development.md).

## Select tests

| Command | Coverage |
| --- | --- |
| `pnpm test:repo` | Repository entrypoints, fixed dependencies and configuration |
| `pnpm test:contract` | Shared contracts and readers |
| `pnpm test:sdk` | External employee SDK contract |
| `pnpm test:references` | Read-only MCP protocol and reference boundaries |
| `pnpm test:bindings` | Client bindings and interaction state |
| `pnpm test:work` | Backend business and database rules |
| `pnpm test:native` | DSH adaptation and execution authorization |
| `pnpm test:extensions` | IM and local retrieval extensions |
| `pnpm --filter @teloa/cli test` | Native installer and release resources |
| `pnpm typecheck` | Build first, then root type checks |
| `pnpm check:client` | Client build boundaries |

Run affected tests first rather than the entire table for every change. Database tests need local Docker; some host tests need built assets, ports or platform capabilities. Read their prerequisites. If scripts change, use the checked-out `package.json` as the authority.

## Validate a small change

For the read-only MCP service:

```sh
pnpm test:references
```

It starts a real stdio service and checks discovery, content, unknown identities, wrong versions and extra arguments. Then read through the [complete client](https://docs.teloa.ai/v/0.2.8/markdown/en/develop/mcp.md), and test employee denial without a grant and success after granting it. This separates protocol, authorization and model issues.

For a defect covered by a single file, run that file directly:

```sh
node --test packages/mcp-reference/tests/protocol.test.ts
```

## Record evidence

Record the source commit, Node/platform version, command, actual exit result and relevant receipts. Preserve the initial reproduction and rerun affected cases after fixing it. List skipped tests, missing dependencies and untested platforms separately.

| Evidence | What it proves |
| --- | --- |
| Reader passes | Input satisfies the current format |
| Scripted model or fixed fixture passes | State, permissions and persistence |
| Real model completes work | Actual behavior for that input and model |
| Browser completes an action | Interaction in that page and state |
| Real tarball installs in a clean environment | That platform's release installation path |

No row substitutes for all the others. Real models require credentials and incur usage; keep those checks separate from ordinary unit tests.

## Installer and runtime checks

Installer changes also require startup, survival after the launching terminal closes, stop/restart, port conflicts, non-ASCII and space-containing paths, backup, restore, upgrade and data-preserving uninstall. Install an actual npm tarball, then verify registry installation after release.

Use a native host with a Docker database for daily development; containers cover database and deployment regression. Linux-container success does not establish macOS or Windows native paths, programs or system permissions.

## Contribute

Submit an Issue or PR to the Community repository with the problem, reproduction, resulting behavior, validation and limits. Follow `CONTRIBUTING.md` and `DCO.md`, including Signed-off-by. Exclude credentials, runtime data, private content and unrelated changes. Report security issues through the private route in `SECURITY.md`.