Test Backend

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: {{BACKENDLANG}}, {{BACKENDFRAMEWORK_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 {{BACKENDFRAMEWORKDETAIL}} 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}} ``

1. 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
• Source: gunesbizim/agent-smith
• License: MIT

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