---
name: backend-testing-auditor
description: "Use when auditing, designing, and hardening backend test suites (unit, integration, E2E, contract). Evaluates test isolation, database state management, flaky async assertions, boundary testing (null, 0, max), and regression prevention."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - testing-patterns
  - tdd-workflow
  - property-based-testing
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
inputs:
  task: "string"
  target_file: "string"
outputs:
  result: "string"
  verification_status: "boolean"
trigger:
  - "backend"
  - "auditor"
---

# Backend Testing & Verification Quality Audit

## Activation Boundaries
- **Activate when:** Use when auditing, designing, and hardening backend test suites (unit, integration, E2E, contract). Evaluates test isolation, database state management, flaky async assertions, boundary testing (null, 0, max), and regression prevention.
- **DO NOT activate when:** The task falls outside the `backend-testing-auditor` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


## Mandatory Pre-Flight Context Inspection
1. **Test Environment Isolation**: Confirm tests run against a dedicated disposable database or isolated mock boundary.
2. **State Cleanup & Transactions**: Verify tests clean up database mutations (e.g. running inside rolled-back transactions).
3. **Flakiness Vectors**: Identify arbitrary `sleep()` or `setTimeout()` delays; replace with condition-based awaiting.
4. **Boundary Coverage**: Check for edge-case test cases (0 values, null, empty strings, max integer, expired timestamps).
5. **Deterministic Clocks**: Ensure tests that assert on time mock or freeze time (`jest.useFakeTimers()`, `time-machine`).

## 🛠️ Technical Architecture & Reference Recipes

### 1. Transaction-Rolled-Back Test Isolation Pattern
```typescript
describe('OrderService Integration', () => {
  let trx: Transaction;

  beforeEach(async () => {
    // Start transaction before each test
    trx = await db.startTransaction();
  });

  afterEach(async () => {
    // Rollback changes completely — guarantees zero cross-test pollution
    await trx.rollback();
  });

  it('deducts inventory atomically when order is placed', async () => {
    const service = new OrderService(trx);
    const result = await service.placeOrder({ sku: 'WIDGET-01', qty: 2 });
    
    expect(result.status).toBe('CONFIRMED');
    const item = await trx.items.findById('WIDGET-01');
    expect(item.stock).toBe(8); // Started with 10
  });
});
```

### 2. Flake-Free Async Assertion Loop
```typescript
// ❌ FLAKY: Blind sleep
await new Promise(r => setTimeout(r, 500));
expect(queue.processedCount).toBe(1);

// ✅ ROCK SOLID: Bounded poll until condition is met or timeout expires
export async function waitFor(
  predicate: () => boolean | Promise<boolean>,
  timeoutMs = 3000,
  intervalMs = 50
): Promise<void> {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    if (await predicate()) return;
    await new Promise(r => setTimeout(r, intervalMs));
  }
  throw new Error(`waitFor timed out after ${timeoutMs}ms`);
}

await waitFor(() => queue.processedCount === 1);
expect(queue.processedCount).toBe(1);
```

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Shared Mutable Test DB** | Concurrent test runners overwrite the same records, causing random failures | Partition test DBs per test runner worker (e.g. `test_db_${JEST_WORKER_ID}`) |
| **Over-Mocking Implementation** | Mocking all internal functions passes tests even when actual integration is broken | Only mock external third-party I/O boundaries (Stripe, Twilio, AWS S3) |
| **Silent Uncaught Rejections** | Asynchronous promise rejections not caught inside test body pass silently | Enable `--unhandled-rejections=strict` in Node test runner |

## 🏛️ Tribunal Verification & Guardrails
- **Active Reviewers:** `test-engineer`, `qa-automation-engineer`, `logic-reviewer`
- **Evidence Standard:** Categorize claims into `[OBSERVED]` test code, `[INFERRED]` coverage gaps, and `[UNVERIFIED]` test execution results.

## 🤖 LLM-Specific Traps Table

| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
|:---|:---|:---|
| **Testing Implementation Details** | Asserting on private component state or internal helper functions | Assert on observable user behaviors, DOM roles, and network outcomes |
| **Flaky Async Assertion** | Using arbitrary setTimeout delays before asserting on asynchronous state | Use waitFor or condition-based queries that poll with timeout bounds |
| **Shared Mutable State** | Reusing database records across concurrent test runners | Isolate test databases per worker or execute in rolled-back transactions |


## Verification (Auto-Remediated)

- [ ] **Verify Execution**: Ensure the output matches the original task requirements.
- [ ] **Safety Check**: Validate that no destructive actions occurred outside the requested scope.