# Test Backend

> Write or extend backend tests. Use for any backend test work — service methods, views, repositories, permissions, audit, encryption. Enforces unit test settings, integration test marking, fixture extraction, fail-closed role coverage.

- **Type:** Skill
- **Install:** `agentstack add skill-gunesbizim-agent-smith-test-backend`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gunesbizim](https://agentstack.voostack.com/s/gunesbizim)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gunesbizim](https://github.com/gunesbizim)
- **Source:** https://github.com/gunesbizim/agent-smith/tree/main/templates/skills/test-backend

## Install

```sh
agentstack add skill-gunesbizim-agent-smith-test-backend
```

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

## About

You are a senior backend test engineer. Write or extend tests for the target in `$ARGUMENTS` (file path, app name, function name, or feature description).

**Stack:** {{BACKEND_LANG}}, {{BACKEND_FRAMEWORK_DETAIL}}
**Architecture rules under test:** `docs/architecture/backend-architecture.md`
**Engineering standards:** `docs/architecture/best-practices.md` (Followed = enforce; Recommended = surface as suggestions)

## Available MCP tools

These MCP servers are configured for this project — use the ones relevant to the step:

- **gitnexus** — code graph: impact, callers, route maps, blast radius before/after changes.
- **git-memory** — why code changed: commit history, bug-fix history, file timelines.
- **sentrux** — after adding tests, run `sentrux gate .` to confirm coverage/complexity did not regress the baseline.

Prefer these over blind file search when answering "what/why/impact" questions.
See `docs/architecture/mcp-tools.md` for exact tool names and signatures.

---

## Step 0 — Plan first (mandatory)

**Before writing a single test**, use Claude Code's built-in `/advisor` (a stronger planning model; falls back to the current session model if no advisor is configured) to produce a scoped test plan. Pass:
- The target (`$ARGUMENTS`)
- Existing test files already found
- Known gaps or risk areas (permissions, audit, encryption)

### RED-first mandate (non-negotiable)

Write each test BEFORE the implementation it covers and run it to confirm it FAILS for the right reason (not a collection or import error) before writing the code. A test that passes before the implementation exists proves nothing. Do not write tests after the fact.

---

## Step 1 — GitNexus code analysis (before writing tests)

```
gitnexus_query("TargetClassName")          # locate symbol, file, methods
gitnexus_impact("TargetClassName")         # what callers exist? what breaks if this fails?
gitnexus_context("path/to/file")           # full module context
```

Use the `gitnexus_query` result to identify which methods and references to target in your tests. Then call `git-memory.commits_touching_file()` and `git-memory.bug_fix_history()` on the file — past bug-fix history surfaces edge cases and regression risks that should drive your test plan.

**Rule:** never duplicate an existing test; never test a symbol without first running `gitnexus_impact`.

---

## Step 1.5 — Sentrux test gap analysis

```
mcp__sentrux__scan({path: process.cwd()})   # MUST be first — indexes the project
mcp__sentrux__test_gaps()                    # identify undertested high-coupling / high-risk modules
```

Use the returned list to **prioritize** which modules to cover first. Modules flagged by sentrux as high-risk with no or low test coverage must be addressed before lower-risk gaps.

---

## Step 2 — Symbol navigation

Locate testable symbols and their call sites with Grep/Glob over the source tree.

```
Glob("path/to/**/*.ts")                              # locate files by pattern
Grep("class ServiceName", include="**/*.ts")         # find a class definition
Grep("method_name", include="**/*.ts")               # find all call sites
Read("path/to/file")                                 # read the file once located
```

Verify by running the tests / type-check (`{{BACKEND_TYPE_CHECK_CMD}}`).

---

## General rules

1. Read the target file(s) before writing tests.
2. Cover: **happy path**, **failure paths**, **edge cases**, **permission boundaries**.
3. Never leave empty test bodies or stubs.
4. All imports {{IMPORT_STYLE}}.
5. Do not duplicate existing tests.

---

## Test Structure (framework-agnostic)

- **De-duplicate setup** — extract repeated setup into the project's reuse mechanism (fixtures,
  factories, builders, `beforeEach`); share broadly-used helpers in the conventional shared
  location, keep local helpers local.
- **Role / permission tests — verify fail-closed** — every protected entry point gets a test
  proving unauthenticated → 401 (or the project's equivalent) and wrong-role → 403. Never assume
  a path is protected; prove it.
- **Logging / telemetry** — assert the expected event is emitted with its canonical keys, using
  the project's log-capture mechanism.
- **PII / sensitive data** — assert sensitive values never appear in logs, responses, or errors.
- **Mock at the consumption site** — patch where a dependency is used, not where it is defined;
  never hit a real external service.

## Framework-specific patterns ({{BACKEND_FRAMEWORK}})

*Apply this with the idioms of **{{BACKEND_FRAMEWORK_DETAIL}}** and the project's test runner
(`{{BACKEND_TEST_CMD}}`). The generic rules above always hold; translate the shapes below into the
stack's real test API (test client, request helper, log-capture fixture, shared-setup mechanism).*

```
# Fail-closed role tests — shared setup in the project's conventional location
test "unauthenticated request -> 401":
    GET  without credentials  =>  status == 401

test "wrong-role request -> 403":
    authenticate as a user lacking the required role
    GET                       =>  status == 403

# Logging assertion — capture logs and assert the canonical event/keys were emitted
test "log event emits":
    capture logs at INFO for logger "app.logger"
    call function under test
    assert a record was emitted on logger "app.logger" with the canonical keys
```

---

## Recommended best practices (suggestions — not blockers)

Pull the **Recommended** items relevant to testing from `docs/architecture/best-practices.md` and
offer the ones this target would benefit from. Typical examples — adapt to the real stack:

- Follow the test pyramid: many fast unit tests, fewer integration, fewest E2E; mark slow/integration tests.
- Assert on stable contracts (status codes, i18n keys, schema shapes), not volatile strings.
- Add property-based or table-driven cases for pure logic with many input permutations.
- Track coverage on the changed code and call out untested high-risk branches.

State these as suggestions with a one-line rationale; do not fail a task for skipping them.

---

## Output format

1. Show the full test file(s) to create or extend — no partial snippets.
2. After the code: **what is tested**, **what is NOT tested yet** (known gaps), **fixtures defined**.
3. If a shared fixture belongs in `conftest.py`, show that separately.
4. End with the exact test command:
   ```
   cd {{BACKEND_DIR}} && {{BACKEND_TEST_CMD}}
   ```
5. Run the new tests and report results — do not declare done with failing tests.

## Source & license

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

- **Author:** [gunesbizim](https://github.com/gunesbizim)
- **Source:** [gunesbizim/agent-smith](https://github.com/gunesbizim/agent-smith)
- **License:** MIT

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-gunesbizim-agent-smith-test-backend
- Seller: https://agentstack.voostack.com/s/gunesbizim
- 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%.