---
name: parallel-agent-test-implementation-alignment
description: |
  Fix test failures when test-writing and implementation agents work in parallel and make
  different assumptions about widget internals. Use when: (1) tests fail with "Found 0 widgets
  with type/icon/text" after parallel agent completion, (2) widget finder expectations don't
  match actual implementations (wrong icon, wrong widget type, wrong text label), (3) parallel
  TDD workflow produces tests that assume CircularProgressIndicator but get shimmer skeletons,
  or assume Icons.send but get Icons.arrow_upward, or assume ListView but get CustomScrollView.
  Covers systematic reconciliation strategy for Flutter widget tests written before implementations.
author: Claude Code
version: 1.0.0
date: 2026-02-09
---

# Parallel Agent Test-Implementation Alignment

## Problem

When using parallel agents (one writing tests, others writing implementations), the test agent
must guess widget internals (icons, widget types, text labels, layout structures) since the
implementation doesn't exist yet. These guesses are wrong ~30% of the time, causing test
failures that are NOT bugs — they're expectation mismatches.

## Context / Trigger Conditions

- **Workflow**: Parallel TDD with separate test and implementation agents
- **Symptom 1**: `Expected: at least one matching candidate / Actual: Found 0 widgets with type "X"`
- **Symptom 2**: `Found 0 widgets with icon "IconData(U+0XXXX)"`
- **Symptom 3**: `Found 0 widgets with text "Cancel"` (expected text button, got icon button)
- **Symptom 4**: Position assertions fail (e.g., `greaterThan` vs `lessThan` for reversed lists)
- **Framework**: Flutter widget tests with `flutter_test`

## Common Mismatch Categories

### 1. Icon Mismatches (Most Common)
| Test Assumes | Implementation Uses | Why |
|---|---|---|
| `Icons.send` | `Icons.arrow_upward` | Modern chat UX preference |
| `Icons.save` | `Icons.check` | Save-as-checkmark pattern |
| Text "Cancel" button | `Icons.close` IconButton | Compact UI choice |

### 2. Widget Type Mismatches
| Test Assumes | Implementation Uses | Why |
|---|---|---|
| `CircularProgressIndicator` | Shimmer skeletons | Better perceived performance |
| `ListView` | `CustomScrollView` with Slivers | Advanced scroll features needed |
| `AlertDialog` | Bottom sheet | Platform conventions |

### 3. Layout/Position Mismatches
| Test Assumes | Reality | Fix |
|---|---|---|
| `firstOffset.dy > thirdOffset.dy` | Reversed list inverts expected positions | Flip comparison operator |

## Solution

### Prevention Strategy (for test agent prompts)

Include these directives in test agent prompts:
```
- Be FLEXIBLE in assertions: check for TYPE existence rather than specific icons/text
- Use find.byType(Widget) over find.byIcon(Icons.specific) where possible
- For buttons, find by tooltip or semantics rather than exact icon
- Note: implementation agents will independently choose icons, widget types, and labels
```

### Reconciliation Strategy (post-parallel completion)

1. **Run tests** — collect all failures
2. **Categorize failures** by mismatch type (icon, widget type, text, position)
3. **Read implementations** — grep for actual icons, widget types, labels used
4. **Batch fix tests** — update expectations to match reality
5. **Re-run tests** — verify all pass

### Efficient Grep Commands for Discovery

```bash
# Find what icons the implementation uses
grep -n "Icons\." lib/presentation/widgets/chat/message_composer.dart

# Find what widget types are used for loading
grep -n "CircularProgress\|Shimmer\|ShaderMask" lib/presentation/widgets/chat/message_list_widget.dart

# Find cancel/save button implementations
grep -n "Cancel\|Save\|Icons.close\|Icons.check" lib/presentation/widgets/chat/message_composer.dart

# Find scroll view type
grep -n "ListView\|CustomScrollView\|SliverList" lib/presentation/widgets/chat/message_list_widget.dart
```

### Fix Patterns

```dart
// BEFORE (test assumed CircularProgressIndicator)
expect(find.byType(CircularProgressIndicator), findsAtLeast(1));

// AFTER (implementation uses shimmer with ShaderMask)
expect(find.byType(MessageBubble), findsNothing); // No real messages in loading
expect(find.byType(ShaderMask), findsAtLeast(1));  // Shimmer effect present

// BEFORE (test assumed Icons.send)
expect(find.byIcon(Icons.send), findsOneWidget);

// AFTER (implementation uses Icons.arrow_upward)
expect(find.byIcon(Icons.arrow_upward), findsOneWidget);

// BEFORE (test assumed text "Cancel" button)
expect(find.text('Cancel'), findsOneWidget);

// AFTER (implementation uses close icon with tooltip)
expect(find.byIcon(Icons.close), findsOneWidget);

// BEFORE (reversed list position assertion was inverted)
expect(firstOffset.dy, greaterThan(thirdOffset.dy));

// AFTER (in reversed list, oldest = top = smaller dy)
expect(firstOffset.dy, lessThan(thirdOffset.dy));
```

## Verification

After reconciliation:
1. All tests pass (0 failures)
2. No implementation files were modified (only test expectations updated)
3. Test intent preserved — each test still validates the correct behavior

## Example

Phase 4 of Spec 007 (Chat Module) launched 3 parallel agents:
- Agent 1: 24 widget tests
- Agent 2: 7 message thread widgets
- Agent 3: 5 composer/reaction widgets

Result: 7/24 tests failed (29%) due to expectation mismatches. All 7 were icon/widget type
mismatches, NOT bugs. Fixed in one pass by reading implementations and updating test expectations.

## Notes

- This pattern applies to ANY parallel TDD workflow, not just Flutter
- The ~30% mismatch rate is consistent across multiple phases
- Delegating the fix to a single agent with explicit mismatch descriptions is most efficient
- Private widgets (prefixed with `_`) can't be found by type in tests — use their visible
  output (e.g., `ShaderMask` for `_ShimmerEffect`)
- Consider using `find.byWidgetPredicate()` or `find.bySemanticsLabel()` for more resilient tests
- Trade-off: More flexible test assertions catch fewer regressions. Balance by testing
  behavior (callbacks fire, state changes) rather than exact UI composition