backend-test

name	backend-test
description	Generate backend tests (unit, integration, mocks) for existing code. Auto-invoke when user says "write test for", "add test", "test this", or "create test".
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
version	2.0.0

Backend Test Generator

Generate backend tests for existing code — typically code that was written without tests, or where additional coverage is needed beyond what a code-writing skill (backend-endpoint) already produced.

When to use this vs. backend-endpoint: backend-endpoint generates tests as part of creating a new endpoint. Use backend-test when the code already exists and you need to add or expand its tests.

When to Invoke

Auto-invoke when user says:

• "Write test for [file/function]"
• "Add test" / "Add tests"
• "Test this"
• "Create test for [thing]"
• "Test the [api/service/function]"

Execution Steps

Step 0: Check Existing Patterns (Phase 0)

Query the knowledge graph for what we know about testing in this project:

PLUGIN_DIR="${CLAUDE_PLUGIN_DIR:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_manager.py" \
  --action query --concept testing \
  --graph-path .agent/knowledge/graph.json 2>/dev/null | head -40

Surface patterns (preferred frameworks, mocking conventions) and pitfalls (flaky-test gotchas). If the graph returns nothing, proceed without it.

Step 1: Locate Code Under Test

If the user named a specific file, use it. Otherwise, ask:

What should I test?
  - File path (e.g., src/services/userService.ts)
  - Function name (e.g., authenticateUser)
  - API endpoint (e.g., POST /api/login)

Read the target file in full so the generated tests cover its actual behavior, not assumed behavior.

Step 2: Detect Test Framework

# Jest
grep -q '"jest"' package.json 2>/dev/null && echo "Jest detected"
# Vitest
grep -q '"vitest"' package.json 2>/dev/null && echo "Vitest detected"
# Mocha
grep -q '"mocha"' package.json 2>/dev/null && echo "Mocha detected"
# Node test runner (built-in)
[ -f "package.json" ] && grep -q '"test":\s*"node --test' package.json && echo "node:test detected"

Detect existing test patterns by reading a peer test file under __tests__/, tests/, or *.test.ts alongside the target.

Step 3: Generate Test File

File location: place tests where existing tests live (mirror the project's convention — colocated *.test.ts next to source, or under a tests/ directory).

Structure (Jest/Vitest):

import { describe, it, expect, beforeEach, vi } from 'vitest';  // or 'jest'
import { {FUNCTION_NAME} } from '{TARGET_PATH}';

describe('{FUNCTION_NAME}', () => {
  describe('happy path', () => {
    it('returns expected result for valid input', () => {
      const result = {FUNCTION_NAME}({VALID_INPUT});
      expect(result).toEqual({EXPECTED});
    });
  });

  describe('error cases', () => {
    it('throws on invalid input', () => {
      expect(() => {FUNCTION_NAME}({INVALID_INPUT})).toThrow();
    });
  });

  describe('edge cases', () => {
    it('handles empty input', () => { /* ... */ });
    it('handles boundary values', () => { /* ... */ });
  });
});

For API/integration tests (supertest pattern):

import request from 'supertest';
import { app } from '{APP_PATH}';

describe('{METHOD} {PATH}', () => {
  it('returns 200 for valid request', async () => {
    const response = await request(app).{method}('{PATH}').send({BODY});
    expect(response.status).toBe(200);
    expect(response.body).toMatchObject({EXPECTED_SHAPE});
  });

  it('returns 4xx for invalid request', async () => {
    const response = await request(app).{method}('{PATH}').send({BAD_BODY});
    expect(response.status).toBe(400);
  });
});

Step 4: Verify

Run the generated tests:

{TEST_COMMAND} {TEST_FILE_PATH}

If any fail because tests assume incorrect behavior, fix the tests, not the source — unless the source has an actual bug. If the source is buggy, surface that to the user; don't silently change it.

Step 5: Emit Execution Summary (Graph Ingestion)

{
  "execution_summary": {
    "skill": "backend-test",
    "task": "tests for {TARGET}",
    "files_created": ["{test file path}"],
    "files_modified": [],
    "tests_added": ["{test file path}"],
    "stack_detected": "{e.g. vitest+supertest}",
    "patterns_followed": [
      {"summary": "{e.g. supertest pattern for HTTP integration tests}", "concepts": ["testing", "api"], "confidence": 0.8}
    ],
    "decisions_made": [
      {"summary": "{e.g. mocked the DB client because tests must run offline}", "concepts": ["testing"], "confidence": 0.75}
    ],
    "pitfalls_avoided": [],
    "assumptions_made": ["{e.g. project uses Vitest globals — no explicit import needed}"]
  }
}

Ingest:

PLUGIN_DIR="${CLAUDE_PLUGIN_DIR:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
echo '<execution_summary JSON>' | python3 "$PLUGIN_DIR/skills/nav-graph/functions/execution_to_graph.py" -

Success Criteria

• Test file located where the project keeps tests (mirrors convention)
• Happy path, error cases, and at least one edge case covered
• Mocks isolate the unit under test
• All generated tests pass on first run (or surface real bugs in the source)
• Execution summary emitted

When NOT to Use This Skill

• You're creating a new endpoint from scratch — use backend-endpoint (it generates tests as part of its workflow)
• You want to test a UI component — use frontend-test