BugMagnet

Systematic test coverage analysis and bug discovery workflow.

Based on gojko/bugmagnet-ai-assistant.

When to Use

• •Analysing test coverage for a module
• •Finding edge cases and potential bugs
• •When code-reviewer identifies test gaps
• •Before releasing critical functionality

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  🔍 ANALYSE  → Understand code and existing tests          │
│  📊 GAP      → Identify missing coverage                   │
│  ✍️  WRITE    → Implement tests iteratively                │
│  🔬 ADVANCED → Deep edge case exploration                  │
│  📋 SUMMARY  → Document findings and bugs                  │
└─────────────────────────────────────────────────────────────┘

STOP and wait for user confirmation between phases.

Phase 1: Initial Analysis (🔍 ANALYSE)

1. •Detect language and testing conventions from file extension and project structure
2. •Read implementation file — understand public API, parameters, state, dependencies
3. •Locate test file — if none exists, ask user about creating one
4. •Check coverage tools — run baseline coverage if available
5. •Read existing tests — understand current coverage and patterns
6. •Check project guidelines — README, CONTRIBUTING for testing conventions
7. •Ask user — "Are there additional files I should review?"

STOP — Wait for user input before proceeding.

Phase 2: Gap Analysis (📊 GAP)

1. •

   Evaluate missing coverage using edge-cases.md checklist:

   • •Boundary conditions
   • •Error paths
   • •State transitions
   • •Complex interactions
   • •Domain-specific edge cases
   • •Violated domain constraints
2. •

   Categorise by priority:

   • •High: Core functionality, error handling, boundaries
   • •Medium: Complex interactions, state management
   • •Low: Rare edge cases, performance
3. •

   Present analysis to user with specific examples

STOP — Ask user which tests to implement.

1. •Clarify undecided behaviour for any gaps with unclear expectations

Phase 3: Iterative Test Implementation (✍️ WRITE)

For each test:

1. •Pick highest priority from the list
2. •Write single test (or 2-3 related tests)
3. •Name describes outcome: "returns X when Y", "throws error when Z"
4. •Run immediately

Handling Failures

• •Test expectation wrong: Update test
• •Bug discovered: Create skipped test with documentation
• •Need more context: Try 2 more variations

When Bug Found

• •Create minimal reproduction
• •Explore surrounding territory (bugs cluster)
• •Document in skipped test — DO NOT FIX, only document

Bug Documentation Format

test.skip('feature returns wrong value - BUG', () => {
    /*
     * BUG: Brief description
     * ROOT CAUSE: Analysis
     * CODE LOCATION: file.js:42
     * CURRENT CODE: snippet
     * PROPOSED FIX: snippet
     * EXPECTED: value
     * ACTUAL: value
     */
    // Failing assertion here
});

Maximum 3 attempts per test — document and move on if stuck.

STOP — Ask user if they want advanced coverage (Phase 4).

Phase 4: Advanced Coverage (🔬 ADVANCED)

Create separate test suite: "bugmagnet session <date>"

Use edge-cases.md for comprehensive coverage:

1. •Complex interactions — multiple features, state across operations
2. •Error handling — specific messages, context preservation
3. •Numeric edge cases — zero, boundaries, special values
4. •Date/time edge cases — leap years, DST, timezones
5. •String edge cases — unicode, whitespace, length
6. •Collection edge cases — empty, nested, duplicates
7. •State transitions — order, repetition, invalid states
8. •Domain-specific — names, emails, URLs, security

Phase 5: Summary (📋 SUMMARY)

## Test Coverage Summary

**Tests Added: X total**
- Category 1 (Y tests)
- Category 2 (Z tests)

**Final Count:**
- X passing tests
- Y skipped tests (bugs documented)

**Bugs Discovered:**
1. Bug name - file.js:line
   - Root cause: ...
   - Proposed fix: ...

Test Writing Guidelines

Naming

• •GOOD: "returns chunks without error when text contains newlines"
• •BAD: "handles newline characters"

Assertions Must Match Title

• •If testing "creates objects with different IDs" → verify IDs differ
• •If testing "preserves order" → check actual order
• •Avoid indirect checks (length when you should check values)

Structure

• •Arrange-Act-Assert pattern
• •One assertion per concept
• •Full expected values, not partial matches

Bug Clusters

When you find one bug, look for similar bugs nearby:

• •Try related edge cases
• •Check similar properties
• •Test related contexts

Reference Files

• •Edge Case Checklist — Comprehensive checklist by type