> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Add high-value regression tests
> Review recent merges and open focused, test-only pull requests for material coverage gaps
The test coverage example reviews recently merged GitHub pull requests, finds
one meaningful regression risk with weak test coverage, adds the smallest
useful tests, and opens a focused pull request after those tests pass.
It does not optimize for a coverage percentage. Cosmetic changes, generated
files, broad snapshots, and behavior-neutral refactors are not reasons to
create a pull request. A run that finds no material gap finishes without
writing to GitHub.
## How it works
```mermaid theme={null}
flowchart LR
Merges[Recent merged
pull requests]
Review[Risk and missing-test
review]
Snapshot[Exact source snapshot
and private baseline]
Tests[Minimal tests and
relevant test commands]
Audit{Test-only
audit passes?}
Pull[Focused pull request]
Report[No-op or blocker report]
Merges --> Review
Review -->|material gap| Snapshot
Review -->|no safe gap| Report
Snapshot --> Tests
Tests --> Audit
Audit -->|yes| Pull
Audit -->|no| Report
```
Every run examines a bounded recent-merge window and selects at most one
coherent gap. The agent downloads the exact default-branch commit it inspected,
keeps a private untouched baseline, follows the repository's own test
instructions, and runs the narrowest relevant validation commands.
The publishing tool compares the tested snapshot with the baseline. It rejects
production changes, unlisted paths, deletions, symlinks, and oversized files
before it can write to GitHub.
## Start with the example
Clone the complete agent, publishing policy, and policy tests from GitHub.
```bash theme={null}
git clone https://github.com/diggerhq/opencomputer-example-test-coverage.git
cd opencomputer-example-test-coverage
npm install
npm test
npm run typecheck
npm run opencomputer -- login
```
## Configure a fixture repository
Start with a disposable repository containing a recent merged change and a
deliberately missing regression test. Set that fixed destination in
`opencomputer/agents/test-coverage/tools/config.ts`:
```ts theme={null}
export const TARGET_REPOSITORY = {
owner: "your-github-owner",
repository: "coverage-agent-fixture",
defaultBranch: "main",
} as const;
export const PUBLISH_ENABLED = false;
```
The destination is code-owned. Pull-request text, prompts, commit messages, and
repository files cannot redirect the publishing tool to another repository.
Create a short-lived, fine-grained GitHub token restricted to the fixture
repository with **Contents: read and write** and **Pull requests: read and
write**. Store it as a Development secret through the hidden prompt:
```bash theme={null}
npm run opencomputer -- secrets set GITHUB_PAT \
--environment development \
--agent current
```
The declared connection limits credential injection to GitHub API requests.
The token is not placed in agent source, prompts, repository URLs, or the
runtime environment. GitHub archive downloads follow the connection's declared
redirect to `codeload.github.com`; they do not require a second secret.
## Test in Development
Watch the source and deploy changes to the remote Development environment:
```bash theme={null}
npm run deploy -- --watch
```
In another terminal, start an explicit run:
```bash theme={null}
npm run session -- \
"Review recent merged code and add the highest-value missing regression tests."
```
With `PUBLISH_ENABLED` set to `false`, the agent can inspect the fixture, edit
its isolated snapshot, run tests, and perform the final audit, but the
publishing tool returns a dry-run result without creating a branch or pull
request.
Review the selected risk, proposed test paths, and observed command results.
If they are correct, set `PUBLISH_ENABLED` to `true`, let the watch deployment
finish, and start a new session with the same request.
The published branch is deterministically named
`test/coverage-`. Repeating the run for the same repository head
returns the existing open pull request rather than creating a duplicate.
After changing the example source, wait for the Development watch deployment
to finish and start a new session. Existing sessions remain pinned to the
deployment with which they started.
## What a dry run looks like
A useful no-op still reports what it reviewed. This run ranked three recent
merges, identified an entitlement gate as the highest-risk candidate, and
named two concrete missing regression cases before deciding whether it could
safely edit or publish tests.
The report is evidence for a human reviewer, not permission to publish. The
agent proceeds only after it materializes the exact repository snapshot, reads
the real test harness, edits test-only paths, and observes the validation
commands succeed.
## Troubleshoot remote runs
### GitHub archive redirect is blocked
Current example source authorizes GitHub's archive redirect from
`api.github.com` to `codeload.github.com`. If a session reports
`502 egress-redirect-blocked` while materializing the repository, update the
example, wait for a new Development deployment, and start a new session.
### Bash capability and launch trust boundary
The example explicitly enables OpenComputer's built-in `bash` tool so the
agent can inspect, edit, and test the materialized repository snapshot. If an
older deployment reports `No Code Mode tools are available`, update the
example, wait for a new Development deployment, and start a new session.
`bash` is a broad capability. Repository files and test scripts are untrusted
code and may execute inside the session runtime. For the initial launch, use a
disposable or non-production repository, restrict the fine-grained token to
that repository, keep `PUBLISH_ENABLED` set to `false`, and review the dry-run
result before enabling publication.
The agent prompt limits shell work to the exact materialized snapshot and
reserves GitHub operations for audited code-defined tools. Those instructions
are behavioral guardrails, not a sandbox boundary. Do not target a sensitive
or production repository until a constrained repository executor replaces the
general-purpose shell.
## Safety boundaries
* The agent can add or update tests and fixtures, but it cannot publish a
production-code testability refactor.
* It cannot merge, approve, close, or label pull requests or change repository
settings.
* Failing, flaky, or environment-dependent tests are reported without
publishing.
* Repository content and test output are treated as untrusted evidence rather
than instructions.
* The initial launch uses a general-purpose shell inside the session runtime;
repository and token scoping remain required even with prompt guardrails.
* This example starts from explicit interactive runs. Add a recurring schedule
only after validating the repository-specific workflow and publication
policy.