# Increase Coverage

> Increase Coverage is an Agent Skill for testing & quality published in the rodydavis/signals.dart repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Systematic guidelines for executing code coverage tools, analyzing gaps in testing, and implementing targeted tests to maximize code coverage across the reactive framework.

- Skill name: `increase-coverage`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/rodydavis/signals.dart/blob/HEAD/.agents/skills/increase-coverage/SKILL.md
- Repository: rodydavis/signals.dart (791 GitHub stars when collected)

## SKILL.md

# Code Coverage Execution and Maximization Guide

This developer skill provides step-by-step instructions and best practices for executing code coverage tools, identifying untested paths (gaps), and writing high-fidelity unit tests to drive coverage to 100% across the monorepo.

---

## 1. Executing and Aggregating Monorepo Coverage

Our monorepo coordinates testing across multiple packages using Melos. Follow this command workflow to generate and merge coverage data:

### A. Run Package Tests with Coverage
Execute the monorepo test runner. This runs `flutter test --coverage` (or `dart test --coverage`) across all packages:
```bash
melos run test
```

### B. Combine Package Coverage Files
Run the combination script to merge individual package-level `coverage/lcov.info` files into a unified root `lcov.info` file:
```bash
melos run coverage
```
> [!NOTE]
> The aggregation script (`scripts/combine_coverage.sh`) dynamically rewrites path roots to be absolute and deletes temporary package `coverage` directories to maintain workspace hygiene.

### C. Generate the HTML Coverage Report
Translate the unified `lcov.info` file into an interactive HTML visualization report using `genhtml` (part of the `lcov` toolkit):
```bash
genhtml lcov.info -o coverage/html
```

---

## 2. Pinpointing Uncovered Lines (Gap Analysis)

To quickly locate untested lines of code without browsing the entire HTML report, run the following `grep` and `awk` pipeline on the root `lcov.info` file:

```bash
grep -E "SF:|DA:" lcov.info | awk -F: '/SF/ {file=$2} /DA/ {split($2,a,","); if(a[2]==0) print file, a[1]}'
```

This output displays the absolute file path followed by the exact line number of every uncovered statement, for example:
```text
/workspace/packages/preact_signals/lib/src/model.dart 21
/workspace/packages/preact_signals/lib/src/model.dart 25
```

---

## 3. Strategies for Reaching 100% Coverage

Once you identify the uncovered lines, apply these targeted testing strategies to write meaningful tests:

### A. Testing Model and Option Basics
Ensure value models, options, and parameters are fully exercised:
- **`copyWith` Methods**: Test with both `null` (to assert fallback to current value) and explicit values.
- **Equality (`==`) and `hashCode`**:
  - Test comparing identical references (`identical(this, other)`).
  - Test comparing distinct instances with identical properties (expect equal).
  - Test comparing distinct instances with differing properties (expect unequal).
  - Test comparing against null or instances of completely different classes.

### B. Exercising Complex Branch/Condition Logic
Examine every nested `if`, `else`, and ternary (`? :`) statement:
- Construct test inputs that force the path to evaluate to `true`.
- Construct test inputs that force the path to evaluate to `false`.
- Ensure bounds checks, empty collections, and null-safety fallbacks are explicitly triggered.

### C. Simulating and Asserting Exception/Catch Paths
To cover recovery logic or diagnostic assertions:
- **`catch` Blocks**: Pass incompatible types or construct scenarios that cause runtime `TypeError` or `AssertionError` to verify fallback branches.
- **Dispose and Lifecycle Errors**: Call `.dispose()` on a signal/primitive, then attempt a read or write operation to assert it throws `SignalsReadAfterDisposeError` or `SignalsWriteAfterDisposeError`.

### D. Deep Recursive Collections
Verify that custom deep collection assertions (such as lists, maps, sets, or nested objects) evaluate both matching and mismatching configurations at every depth.

---

## 4. Housekeeping and Version Safety

Before finalizing the coverage maximization run, verify repository hygiene:

1. **Format test files**:
   ```bash
   dart format .
   ```
2. **Run Lints & Static Analysis**:
   ```bash
   melos run analyze
   ```
3. **Clean Git State**:
   Never check coverage files (`lcov.info` or `coverage/`) into Git history. If they are accidentally staged, remove them:
   ```bash
   git rm -r --cached coverage/
   git rm lcov.info
   ```

---

Source: https://www.openparable.com/skill/testing-quality/increase-coverage (OpenParable). Cite the canonical URL above.
