Cheetah / Cheetah documentation

Verify a custom integration

An interface implementation, handler, or client is complete only when it preserves the behavior its neighbors rely on. Type compatibility proves that the pieces connect. It does not prove identity, ordering, fencing, authorization, cleanup, or recovery across a real command journey.

Use the smallest proof that can answer the claim, then add a complete end-to-end run for every boundary the extension changes.

Choose the proof level from the claim

“Tests passed” is useful only with the tested topology, client type, action, failure conditions, and observed evidence. A browser protocol actor does not prove content-script behavior. An in-memory host does not prove Redis coordination. A terminal result does not prove an external effect unless the target or product record independently confirms it.

Begin with the repository checks

After preparing the source checkout, run the focused suite for the package you changed. The common entry points are:

python scripts/ci_check.py --quick

cd serverCheetah
pytest tests/unit/ -v --tb=short

cd cheetahClient
npm test

These commands use the repository's prepared environments and declared dependencies. Narrow them to the relevant test file while developing, then include the appropriate package or repository check before making a broader claim.

Prove a custom handler as a contract

A handler test should cover more than its success payload:

1. register the handler and matching descriptor before runtime startup;
2. reject missing or invalid arguments at the documented boundary;
3. prove an allowed invocation and every sensitive denial path;
4. exercise required local policy and approval behavior;
5. verify progress, cancellation, and lease invalidation at safe points;
6. return stable structured success and error shapes;
7. confirm capture or parser preflight when the action advertises those features;
8. observe cleanup after success, failure, timeout, disconnect, and runtime stop.

Test the platform effect separately. A browser handler needs a real tab or page lane for browser authority. A console handler that touches files or processes needs an isolated working directory and local-policy boundary. Mocking the handler host is useful for protocol behavior but is not evidence that the actual platform operation works.

Prove a replacement component with its neighbors

For a registry, dispatcher, history, correlator, notifier, policy source, or storage replacement, exercise the invariant shared with adjacent components. Include duplicate and stale-instance input, ordering, empty state, pagination, restart, shutdown, missed notification, and failure of its backing service where relevant.

Distributed replacements need at least one multi-process run. Tenant-aware replacements also need colliding user, client, command, stream, and timing inputs that demonstrate isolation under both success and denial. A compatible method signature or capability marker does not establish those properties.

Keep one maintained command proof through the replacement: authenticate, register, admit, deliver, ACK, execute, return over HTTP, retain, notify, observe, and drain. If the replacement changes only one stage, assert that stage directly while preserving the rest as a regression boundary.

Prove a custom client against the wire and lifecycle

A custom transport or runtime should satisfy the protocol conformance checklist. Use the public Python models and validators and the public TypeScript package exports rather than copying a private runtime shape.

At minimum, test exact hello compatibility, stable client identity across reconnect, new instance identity after replacement, ACK fencing, authenticated HTTP return, deduplication, malformed input, reserved keys, state-report atomicity, uncertain send, and late return. Advertise only actions the current composition can execute.

Then add the platform lifecycle: browser service-worker eviction and page reconstruction, console process and flow cleanup, cooperative-page reload, or native bridge pause/resume. The common protocol contract does not remove the platform's own lifetime and authority.

Use the System Test Lab for bounded ecosystem proof

The repository's systemTestLab/ owns isolated run identity, source provenance, ports, processes, disposable Redis, temporary Chrome profiles, independent expectations, evidence, and ownership-proved cleanup. Check its prepared environment without installing anything:

systemTestLab\bootstrap.cmd --check

Run its own tests and inspect the available proof commands:

systemTestLab\run_tests.cmd
systemTestLab\run_lab.cmd --help

Representative bounded runs include:

systemTestLab\run_lab.cmd prove-in-memory-console
systemTestLab\run_lab.cmd prove-in-memory-complete-browser
systemTestLab\run_lab.cmd prove-redis-multi-process-dual-client
systemTestLab\run_lab.cmd prove-tenant-isolation --topology redis-multi-process

Choose a run whose topology and client actually intersect the changed boundary. Do not run every campaign as ritual, and do not report a passing scenario as proof for capabilities it did not exercise. Lab hosts are disposable proof hosts, not deployment templates.

Preserve evidence another person can evaluate

Record the source revision and dirty state, runtime and dependency versions, build identity, configuration with secrets removed, selected topology, client and runtime identities, action and target, command and trace IDs, expected outcome, observers, start and end time, cleanup result, and known exclusions.

The strongest report states exactly what the run established and what remains outside it. This makes the extension understandable to a human reviewer or an AI agent without turning one green result into an unlimited compatibility claim.

Operate the resulting system

Protocol validation and conformance