# Integration Test Guard

> >

- **Type:** Skill
- **Install:** `agentstack add skill-hybridlabor-api-bdb-dev-optimized-agent-skills-integration-test-guard`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hybridlabor-api](https://agentstack.voostack.com/s/hybridlabor-api)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [hybridlabor-api](https://github.com/hybridlabor-api)
- **Source:** https://github.com/hybridlabor-api/bdb-dev-optimized-agent-skills/tree/main/mcps/touchdesigner-mcp/.claude/skills/integration-test-guard

## Install

```sh
agentstack add skill-hybridlabor-api-bdb-dev-optimized-agent-skills-integration-test-guard
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Integration Test Guard

When you change the **MCP server / API surface**, add or update an integration
test in `tests/integration/`. The `integration-test-guard` hook blocks
`git push` when the outgoing commits touch API/MCP source without one (override
with `SKIP_ITEST_GUARD=1` only when a test genuinely does not apply).

## What counts as "API/MCP surface"

`src/api/**` (OpenAPI schema) · `src/features/tools/**` (tool defs + handlers) ·
`src/server/**` (MCP server) · `src/tdClient/**` (TD HTTP client) ·
`src/transport/**` (stdio/HTTP transport) · `td/modules/mcp/**` (TD-side Python API).

## Step 1 — pick the right suite (by what the change affects)

| Change affects | Suite | Needs live TD (9981)? |
|---|---|---|
| MCP tool **response shape / formatting**, tool registration, manifest | `tests/integration/mcpToolsResponse.test.ts` | No — uses `server.getTool(...)` with mocked client |
| **Client ↔ WebServer behavior** (create/update/delete/exec, TD-side Python) | `tests/integration/touchDesignerClientAndWebServer.test.ts` | **Yes** — real `TouchDesignerClient` over HTTP |
| **HTTP transport** (sessions, `/mcp`, `/health`) | `tests/integration/httpTransport.test.ts` | No live TD, but starts the HTTP server |

If the change spans two categories, cover each in its suite.

## Step 2 — add / update the test

Follow the existing patterns in the chosen file:

- **mcpToolsResponse**: get the tool via `server.getTool(TOOL_NAMES.X)`, invoke its
  handler with a mocked TD client, assert the formatted response shape.
- **touchDesignerClientAndWebServer**: use the shared `tdClient` and the
  `test_base_comp` sandbox (created in `beforeAll`); exercise the real call path,
  then **reconcile against a runtime value** (read it back and compare) rather
  than trusting the response alone. Clean up created nodes.

Prefer reconciliation (compute a value, compare to an invariant) over assertions
that can be satisfied without the behavior actually working.

## Step 3 — run it

```bash
# TD-independent suites:
npx vitest run tests/integration/mcpToolsResponse.test.ts
npx vitest run tests/integration/httpTransport.test.ts

# Live-TD suite (needs TouchDesigner running with the .tox on 9981):
TD_WEB_SERVER_HOST=http://127.0.0.1 TD_WEB_SERVER_PORT=9981 \
  npx vitest run tests/integration/touchDesignerClientAndWebServer.test.ts -t "" \
  --hookTimeout=60000 --testTimeout=60000
```

Notes:
- The live-TD suite's `beforeAll` creates a sandbox base COMP; on a **cold**
  connection the default 10s hook timeout can trip — pass `--hookTimeout=60000`.
- To bring up a real TD and load the `.tox`, use the **`touchdesigner-self-debug`** skill.
- A fresh worktree needs `npm install && npm run gen` before the client/schema exist.

## Step 4 — commit & push

Once the test is added and green, commit and push normally. If a change
legitimately needs no integration test (pure refactor, comment, type-only),
push with `SKIP_ITEST_GUARD=1 git push ...` and say why.

## Related

- `touchdesigner-self-debug` — start TD, load the `.tox`, verify TD-side Python.
- Hook: `.claude/hooks/integration-test-guard.mjs` (Node; PreToolUse on `git push`).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hybridlabor-api](https://github.com/hybridlabor-api)
- **Source:** [hybridlabor-api/bdb-dev-optimized-agent-skills](https://github.com/hybridlabor-api/bdb-dev-optimized-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hybridlabor-api-bdb-dev-optimized-agent-skills-integration-test-guard
- Seller: https://agentstack.voostack.com/s/hybridlabor-api
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.