---
status: pending
priority: p3
issue_id: "011"
tags: [testing, readability, agents, vendors, assertions]
dependencies: []
---

# Add Assertion Messages to Improve Agent-Readable Test Output

## Problem Statement

Most assertions in vendors_test.clj lack custom messages, making failures hard for automated agents to interpret and debug. Adding messages would:
- Improve automated failure analysis
- Make test output self-documenting
- Help future developers understand failures

## Findings

**From agent-native-reviewer:**

**Current assertions without messages:**
```clojure
(is (seq? vendors))
(is (number? matching-count))
(is (= 0 (count vendors)))
(is (contains? result :ids))
```

**Better with messages:**
```clojure
(is (seq? vendors) "Expected vendors to be a sequence")
(is (number? matching-count) "Expected matching-count to be a number, got: %s" (type matching-count))
(is (= 0 (count vendors)) "Expected empty vendor list when database is empty, found %d vendors" (count vendors))
```

**Benefits:**
- Agents can understand what went wrong without reading code
- Self-documenting test output
- Easier debugging when tests fail

## Proposed Solutions

### Option A: Add Messages to All Assertions (Recommended)
**Effort:** Small (20 minutes)
**Risk:** Low

Add descriptive messages to all `is` assertions:
```clojure
;; Before:
(is (= 200 (:status result)))

;; After:
(is (= 200 (:status result))
    "Expected 200 status, got %d" (:status result))
```

**Pros:**
- Maximum clarity for agents and humans
- Self-documenting failures

**Cons:**
- Adds verbosity
- More code to maintain

### Option B: Add Messages to Complex Assertions Only
**Effort:** Small (10 minutes)
**Risk:** Low

Only add messages to non-obvious assertions:
```clojure
;; Keep simple assertions as-is:
(is (= 200 (:status result)))

;; Add messages to complex ones:
(is (>= (:count result) 3)
    "Expected at least 3 vendors (2 new + 1 from setup), got %d"
    (:count result))
```

**Pros:**
- Less verbose
- Focus on non-obvious assertions

**Cons:**
- Inconsistent coverage
- Agents still can't understand simple failures

## Recommended Action

**Go with Option B** - add messages to complex/value-checking assertions first. This provides the most value with less overhead.

Priority assertions to enhance:
1. Lines 53, 64: Magic number assertions with `>=`
2. Lines 110, 117: Status code and count assertions
3. Lines 176-177: Field value assertions

## Technical Details

**High-Priority Assertions:**
- Line 53: `(is (>= (:count result) 3))`
- Line 64: `(is (>= matching-count 3))`
- Line 110: `(is (= 200 (:status result)))`
- Line 117: `(is (= 0 (count remaining-sources)))`

**Message format:**
```clojure
(is assertion "Expected X, got Y: %s" value)
```

**Verification:**
```bash
lein test auto-ap.ssr.admin.vendors-test  # Test failure messages
```

## Acceptance Criteria

- [ ] Complex assertions have descriptive messages
- [ ] Messages explain expected vs actual values
- [ ] Tests still pass
- [ ] Code formatted with lein cljfmt

## Work Log

### 2026-02-07 - Initial Creation

**By:** Agent-Native Reviewer Agent

**Actions:**
- Identified lack of assertion messages
- Documented benefits for automated agents
- Prioritized which assertions need messages most

**Learnings:**
- Assertion messages critical for agent-based development
- Most assertions in file lack messages
- Focus on complex/value-checking assertions first