Mocking Chariot Task

Don't use for:

• Pure business logic (no external calls)
• Integration tests requiring real services

Three-File Pattern

1. Main capability file (capability.go):

// Add between Match() and Invoke() methods
func (c *YourCapability) MockCollectors(target *model.TargetType) []xyz.XYZOption {
    return []xyz.XYZOption{
        xyz.WithCLICollector(NewMockYourCapabilityCLICollector(target)),
        xyz.WithHTTPCollector(NewMockYourCapabilityHTTPCollector(target)),
        xyz.WithDNSCollector(NewMockYourCapabilityDNSCollector(target)),
    }
}

2. Mock file (capability_mock.go):

// Mock capability constructor
func NewMockYourCapability(job model.Job, target *model.TargetType) model.Capability {
    return NewYourCapability(
        job,
        target,
        xyz.WithCLICollector(NewMockYourCapabilityCLICollector(target)),
        xyz.WithHTTPCollector(NewMockYourCapabilityHTTPCollector(target)),
    )
}

// Mock CLI collector with command registration
func NewMockYourCapabilityCLICollector(target *model.TargetType) cli.CLICollector {
    c := cli.NewMockCLICollector()
    c.MustRegisterCommand(`nmap -sV .*`, generateNmapOutput(target))
    return c
}

// Mock HTTP collector with URL registration
func NewMockYourCapabilityHTTPCollector(target *model.TargetType) http.HTTPCollector {
    c := http.NewMockHTTPCollector()
    // Exact URL (no escaping needed)
    c.MustRegisterHTTP("GET", "https://api.example.com/data", http.CannedHTTPResponse{
        StatusCode: 200,
        Body:       generateAPIResponse(target),
    })
    return c
}

// Helper to generate target-specific mock data
func generateNmapOutput(target *model.TargetType) string {
    return fmt.Sprintf("PORT STATE SERVICE\n22/tcp open ssh\n")
}

3. Test file (capability_mock_test.go):

func TestYourCapability(t *testing.T) {
    asset := model.NewAsset("acceptance.com", "192.168.1.1")
    port := model.NewPort("tcp", 22, &asset)
    job := model.NewJob("your-capability", &port)

    task := NewMockYourCapability(job, &port)
    aws := mock.NewMockAWS("[email protected]")

    invoker := mock.NewInvoker(aws, task)
    err := invoker.Invoke()
    require.NoError(t, err)

    // Create expected objects
    expectedRisk := model.NewRisk(&asset, "vuln-name", model.TriageHigh)

    // Perform assertions
    assertions.GraphItemExists(t, aws, &expectedRisk)
    assertions.GraphSize(t, aws, 1)
}

Mock Registration Quick Reference

HTTP URL Matching: Exact vs Pattern

Prefer exact matching (no escaping):

// ✅ RECOMMENDED - Exact URL
c.MustRegisterHTTP("GET", "https://api.example.com/data", response)

// ❌ AVOID - Pattern when exact works
c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/data`, response)

Use patterns only when needed:

// ✅ CORRECT - Dynamic segments
c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/users/.*`, response)
c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/search\?q=.*`, response)

HTTP Collector Quick Reference

Exact URL matching (preferred when possible):

c.MustRegisterHTTP("GET", "https://api.example.com/data", response)

Pattern matching (for dynamic URLs):

c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/users/.*`, response)

Common patterns:

// Query parameters
c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/.*\?id=\d+`, response)

// Path segments
c.MustRegisterHTTPPattern("GET", `https://api\.example\.com/.*/details`, response)

Multiple entity types with correct JSON fields:

// Entity types and their JSON reference field names (deterministic order)
entities := []struct {
    name    string
    refName string
}{
    {"orgs", "orgRef"},
    {"customers", "customerRef"},
    {"asns", "asnRef"},
    {"nets", "netRef"},
}

for _, entity := range entities {
    // Use pattern for dynamic org name
    pattern := fmt.Sprintf(`https://api\.example\.com/%s;name=.*`, entity.name)

    // JSON response uses correct field name for each entity type
    body := fmt.Sprintf(`{
        "%s": {
            "%s": [
                {"@handle": "MOCK-%s-1", "@name": "Example Org 1"},
                {"@handle": "MOCK-%s-2", "@name": "Example Org 2"}
            ]
        }
    }`, entity.name, entity.refName, entity.name, entity.name)

    c.MustRegisterHTTPPattern("GET", pattern, http.CannedHTTPResponse{
        StatusCode: 200,
        Body:       body,
    })
}

Testing Failure Modes

Mock collectors should test both success and failure scenarios to ensure proper error handling:

HTTP Error Responses

// Test 500 Internal Server Error
c.MustRegisterHTTP("GET", "https://api.example.com/data", http.CannedHTTPResponse{
    StatusCode: 500,
    Body:       `{"error": "internal server error"}`,
})

// Test 404 Not Found
c.MustRegisterHTTP("GET", "https://api.example.com/missing", http.CannedHTTPResponse{
    StatusCode: 404,
    Body:       `{"error": "not found"}`,
})

// Test 429 Rate Limit
c.MustRegisterHTTP("GET", "https://api.example.com/throttled", http.CannedHTTPResponse{
    StatusCode: 429,
    Body:       `{"error": "rate limit exceeded"}`,
})

Timeout Handling

// Test timeout scenario (capability should handle gracefully)
// Mock collector returns response, but capability may have timeout logic
c.MustRegisterHTTP("GET", "https://api.example.com/slow", http.CannedHTTPResponse{
    StatusCode: 200,
    Body:       `{"data": "response"}`,
    // Note: Actual timeout testing may require capability-level context cancellation
})

Empty and Malformed Responses

// Empty response body
c.MustRegisterHTTP("GET", "https://api.example.com/empty", http.CannedHTTPResponse{
    StatusCode: 200,
    Body:       "",
})

// Malformed JSON
c.MustRegisterHTTP("GET", "https://api.example.com/malformed", http.CannedHTTPResponse{
    StatusCode: 200,
    Body:       `{"incomplete": "json"`,  // Missing closing brace
})

// Unexpected data structure
c.MustRegisterHTTP("GET", "https://api.example.com/unexpected", http.CannedHTTPResponse{
    StatusCode: 200,
    Body:       `{"wrong": "schema", "missing": "expected_field"}`,
})

CLI Command Failures

// Command exits with error
c.MustRegisterCommand(`failing-command.*`, "Error: command failed\nexit status 1")

// Empty output
c.MustRegisterCommand(`empty-command.*`, "")

// Malformed output
c.MustRegisterCommand(`malformed-command.*`, "Not the expected format")

Test Assertions for Failures

// Verify capability handles errors gracefully
func TestCapabilityHTTPError(t *testing.T) {
    asset := model.NewAsset("test.com", "192.168.1.1")
    job := model.NewJob("capability-name", &asset)

    // Create mock with error response
    mockHTTP := http.NewMockHTTPCollector()
    mockHTTP.MustRegisterHTTP("GET", "https://api.example.com/data", http.CannedHTTPResponse{
        StatusCode: 500,
        Body:       `{"error": "server error"}`,
    })

    task := NewYourCapability(job, &asset, xyz.WithHTTPCollector(mockHTTP))
    aws := mock.NewMockAWS("[email protected]")

    invoker := mock.NewInvoker(aws, task)
    err := invoker.Invoke()

    // Verify error is handled (not propagated as panic)
    require.NoError(t, err)

    // Verify no spurious graph items created
    assertions.GraphSize(t, aws, 0)
}

Common Mistakes

Reference Examples

Complete implementations:

• Nuclei: capabilities/nuclei/nuclei.go - func (n *Nuclei) MockCollectors(port *model.Port), nuclei_mock.go (constructors)
• WHOIS: capabilities/whois/whois.go - func (task *Whois) MockCollectors(asset *model.Asset), whois_mock.go
• EDGAR: capabilities/edgar/edgar.go - func (task *EDGAR) MockCollectors(preseed *model.Preseed), edgar_mock.go (HTTP patterns, date filtering)

Collector interfaces:

• CLI: collector/cli/cli.go
• HTTP: collector/http/http.go
• DNS: collector/dns/dns.go

Full documentation: modules/chariot/backend/pkg/tasks/collector/CLAUDE.md

Maintenance Note: Why No Line Numbers?

This skill uses method signatures instead of static line numbers for code references.

Rationale:

• Line numbers drift with every code change (inserts, deletions, refactors)
• Creates maintenance debt to keep skills synchronized
• Method signatures are stable across refactors
• Grep-friendly: rg "func.*MockCollectors" finds the method instantly

Pattern for references:

✅ GOOD: file.go - func (c \*Capability) MethodName(...)
✅ GOOD: file.go (between Match() and Invoke() methods)
❌ AVOID: file.go:123-127 (will become outdated)

When updating this skill: Preserve method-based references, avoid adding line numbers