integreat/todos/011-pending-p3-add-assertion-messages.md

status, priority, issue_id, tags, dependencies

status	priority	issue_id	tags	dependencies
pending	p3	011	testing readability agents vendors assertions

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:

(is (seq? vendors))
(is (number? matching-count))
(is (= 0 (count vendors)))
(is (contains? result :ids))

Better with messages:

(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:

;; 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:

;; 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:

(is assertion "Expected X, got Y: %s" value)

Verification:

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