erofs-freebsd-out-tree/tests/TEST-COVERAGE-MATRIX.md

# Test Coverage Matrix - repo-pre-15

## Overview
Test specifications for the implemented FreeBSD EROFS paths. A listed test case
is not proof that every environment has executed it. Historical TC000-TC161
evidence remains under `tests/results/manual/`; Pre15 bounded runs use immutable
manifests from `tests/pre15/`.

## Coverage Summary
- **Specification IDs**: TC000-TC161; TC000 is a template
- **Executable results**: 161 total, 160 PASS, TC146 PARTIAL
- **Open kernel failures**: none
- **Approved gap**: positive explicit mapped-payload fixture for TC146
- **Pre15 test-only addition**: TC162 legacy xattr prefix carrier contract
- **No automated coverage percentage is claimed**

## Feature-to-Test Mapping

### 1. Mount Operations (Features 1-2)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| mount / umount | TC001, TC007, TC008 | Normal, concurrent, with-errors |
| statfs | TC009, TC010 | Basic, 48-bit blocks |

### 2. Root & VNode (Features 3-4)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| root vnode lookup | TC011 | Normal |
| vget | TC012, TC013 | Normal, invalid nid |

### 3. Superblock (Features 5-7)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| superblock parsing | TC014, TC015 | Normal, corrupted |
| superblock CRC32C verification | TC002, TC016 | Valid, invalid |
| 48-bit block count parsing | TC017, TC018 | Normal, large FS |
| 48-bit root nid parsing | TC019 | Normal |

### 4. Inode Formats (Features 8-15)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| compact inode decoding | TC020, TC021, TC022 | Basic, flag-based nlink=1, Linux dev decode |
| extended inode decoding | TC023, TC024 | Normal, large file |
| compact inode link-count handling | TC025 | Flagged single link, explicit hard links, directories |
| dot_omitted handling | TC026, TC027 | With/without |
| uncompressed FLAT_PLAIN read | TC028, TC029, TC030 | Small, medium, large |
| uncompressed FLAT_INLINE read | TC031, TC032 | Normal, zero-length |
| inline tailpacking read | TC033, TC034, TC147 | Normal, boundary, metadata-block/image bounds |

### 5. File Operations (Features 16-18)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| regular file read | TC035, TC036, TC037 | Sequential, random, large |
| symlink read | TC038, TC039, TC040 | Short, long, broken |
| directory entry decoding | TC041, TC042, TC141, TC148 | Normal, large, shared validator, Linux tail padding |

### 6. Directory Operations (Features 19-22)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| lookup | TC043, TC044, TC045 | Found, not-found, case |
| readdir | TC046, TC047, TC048, TC160 | Basic, large, restart cookies, `OFF_MAX` corruption |
| . handling | TC049 | Dot entry |
| .. handling | TC050 | Dotdot entry |

### 7. VFS Integration (Features 23-28)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| namecache integration | TC051, TC052 | Hit, miss |
| vfs_hash integration | TC053 | Normal |
| vn_vget_ino integration | TC054 | Normal |
| getattr | TC055, TC056, TC158 | Compressed 48-bit allocation, generation, decoded special rdev |
| access | TC057, TC058 | Allowed, denied |
| readlink | TC059 | Normal |
| pathconf | TC060 | All queries |

### 8. Read-Only (Features 29)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| read-only setattr rejection | TC061, TC062, TC063, TC159 | chmod, chown, write, combined special-vnode attributes |

### 9. VM Integration (Features 30-31)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| FreeBSD local vnode pager | TC064, TC065, TC149 | Sync/async ABI, real randomized mmap faults |
| explicit vop_bmap unsupported | TC066, TC149 | Local pager fallback without strategy assumptions |

### 10. Extended Attributes - Shared (Features 32-36)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| shared user.* xattr scan | TC067, TC068 | Found, not-found |
| shared user.* xattr list | TC069 | Multiple |
| shared trusted.* xattr get | TC070 | Normal |
| shared security.* xattr get | TC071 | Normal |
| shared system xattr list | TC072 | Normal |

### 11. Extended Attributes - Container (Features 37-40)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| shared-ea-in-metabox container | TC073 | Normal |
| inline user.* xattr | TC005, TC074 | Normal, multiple |
| inline trusted.* xattr | TC075 | Normal |
| inline security.* xattr | TC076 | Normal |

### 12. Extended Attributes - Advanced (Features 41-46)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| long-prefix user.* xattr | TC077 | Long name |
| long-prefix trusted.* xattr | TC078 | Long name |
| packed prefix table | TC079, TC080 | Normal, lookup |
| legacy prefix primary fallback | TC162 | Checksum-valid legacy/plain/packed/metabox and exact negatives |
| metabox-backed shared xattr | TC081 | Normal |
| system namespace xattr subset | TC082 | Specific attrs |
| user namespace xattr subset | TC083 | Filtering |

### 13. Compression - LZ4 (Features 47-51)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| LZ4 compression support | TC003, TC084, TC085 | Small, large, corrupt |
| LZ4 compressed data path | TC086, TC087 | Full source compare, deterministic offset compares |
| LZ4 compression config handling | TC088 | Different configs |
| LZ4 compressed pcluster mapping | TC089, TC090 | 4KB, 64KB |
| ztailpacking data path | TC091, TC092 | Normal, edge |

### 14. Chunk-Based (Features 52-53)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| chunk-based inode data path | TC093, TC094 | Single-dev, multi-dev |
| chunk index read path | TC095 | Normal |

### 15. Multi-Device (Features 54-57)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| device table support | TC096, TC097 | Parse, invalid |
| fragments support | TC098 | Normal |
| multi-device support | TC006, TC099, TC100 | 2-dev, 4-dev, errors |
| unified address to device mapping | TC101 | All devices |

### 16. Compression - DEFLATE/zstd (Features 58-59)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| DEFLATE compressed data path | TC102, TC103, TC104 | Level 1 full/range compare, levels 6 and 9 |
| zstd compressed data path | TC105, TC106, TC107 | Level 1, 15, 22 |

### 17. Compression - LZMA (Feature 60)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| LZMA/MicroLZMA compressed data path | TC004, TC108, TC109, TC110 | Normal, large, micro, corrupt |

### 18. Documentation (Feature 61)
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| manual pages | TC111 | Accuracy check |

### 19. Error Handling (Additional Paths)
| Scenario | Test Cases | Coverage |
|---------|-----------|----------|
| Invalid superblock magic | TC112 | Mount failure |
| Corrupted inode | TC113 | Read error |
| Out-of-bounds block | TC114 | Access error |
| Unsupported algorithm | TC115 | EOPNOTSUPP |
| Targeted compressed-stream corruption | TC116 | Equal provider length, proven extent, EIO |
| Invalid xattr format | TC117 | Parse error |
| Device not found | TC118 | Multi-dev error |
| Uncompressed payload integrity boundary | TC119 | No per-file CRC; source hash detects mutation |

### 20. Boundary & Stress (Additional Paths)
| Scenario | Test Cases | Coverage |
|---------|-----------|----------|
| Empty file read | TC120 | Zero-length |
| Maximum file size | TC121 | 16TB limit |
| Deep directory tree | TC122 | 100+ levels |
| Long filename | TC123 | 255 chars |
| Many small files | TC124 | 10000+ files |
| Large directory | TC125 | 10000+ entries |
| Concurrent reads | TC126 | Multi-threaded |
| Memory pressure | TC127 | Low memory |
| Sequential throughput | TC128 | Performance |
| Random read pattern | TC129 | Performance |
| Mixed workload | TC130 | Realistic |

## Execution Path Coverage

### Normal Paths (Green)
The matrix maps implemented paths to manual procedures. See dated reports for
the subset actually executed on a given FreeBSD 15 environment.

### Error Paths (Red)
- Mount errors: TC007, TC008, TC112
- Read errors: TC113, TC114, TC116
- Lookup errors: TC044, TC117
- Permission errors: TC061-TC063
- Device errors: TC097, TC118
- Compression errors: TC085, TC104, TC110, TC116
- CRC errors: TC002, TC016
- End-to-end payload authenticity boundary: TC119

### Boundary Conditions (Yellow)
- Zero-length: TC032, TC120
- Maximum size: TC018, TC121
- Deep nesting: TC122
- Long names: TC077, TC078, TC123
- Large collections: TC042, TC048, TC124, TC125
- Edge alignments: TC034, TC090, TC092
- Inline metadata block: TC147
- Directory tail padding: TC148
- VM EOF/private mapping: TC149
- 48-bit fallback superblock union: TC150
- Extended inode `OFF_MAX` rejection: TC151
- Multi-GiB compressed extent holes: TC152
- Directory block indexes above `INT_MAX`: TC153
- Explicit extent global order: TC157
- Extended compressed allocation high bits: TC158
- Combined special-vnode setattr: TC159
- Dot-omitted `OFF_MAX` cookie: TC160
- Build-tool failure propagation: TC161

## Test Execution Order
1. Basic mount (TC001-TC002)
2. Core functionality (TC003-TC060)
3. Extended features (TC061-TC111)
4. Error handling (TC112-TC119)
5. Stress and NFS tests (TC120-TC133)
6. Metadata/compression completion (TC134-TC149)
7. Final correctness findings and build qualification (TC150-TC161)

## Coverage Metrics

No line, branch, path, or feature percentage is asserted. The repository does
not contain an instrumented kernel coverage run or CI harness.

The historical TC000-TC161 suite remains procedure-driven.
`tests/pre15/run-host.sh`, `run-build.sh`, `run-qemu.sh`, and `run-smoke.sh`
provide the bounded Pre15 adapter. They discover exact case files, preserve raw
stdout/stderr and hashes, separate DUT/runner/infrastructure failures, and make
cleanup success part of PASS. This does not claim full-suite automation.

## Test Case Status

- [x] Specifications TC000-TC161 are present exactly once.
- [x] Execution checklist and result templates are present.
- [x] Dated manual reports record qualified runs and real limitations.
- [x] TC150-TC152 have final-module FreeBSD 15 evidence.
- [x] TC153 has exact-source sparse-provider FreeBSD 15 evidence.
- [x] TC154-TC156 have final-module FreeBSD 15 evidence.
- [x] TC157-TC161 have independent final-source FreeBSD 15 evidence.
- [x] Final result is 160 PASS and TC146 PARTIAL.
- [ ] Automated kernel regression/coverage infrastructure is not implemented.
- [x] Pre15 B01 runner controls and TC162 host contract are implemented.

### 21. Compression P0 Completion
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| fragment-backed compressed metabox | TC142 | Positive, loop, recursive NID, bounds |
| DEFLATE/ZSTD partial reference | TC143 | Full, partial, random, corrupt |
| MicroLZMA completion semantics | TC144 | Input consumption, partial, corrupt |
| FreeBSD ZSTDIO build gate | TC145 | Disabled/enabled build and KLD |
| HEAD2/interlaced/extent mapping | TC146 | HEAD2/interlaced PASS; explicit mapped payload PARTIAL |

### 22. Metadata and VFS Semantics
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| FLAT_INLINE metadata-block and declared bounds | TC147 | Positive and checksum-valid cross-block corruption |
| Linux-compatible directory tail padding | TC141, TC148 | Cold lookup, readdir, cookies, strict corruptions |
| Real FreeBSD vnode pager faults | TC064-TC066, TC149 | Plain/LZ4, random faults, EOF, SIGBUS, private COW |
| Linux special-device decode | TC022, TC056 | Compact/extended char, block, FIFO `st_rdev` |
| Real compressed allocation accounting | TC055, TC158 | Algorithms/shapes and extended 48-bit block count |
| Stable per-inode NFS generation | TC132, TC154 | Stable metadata; changed inode metadata makes old handles stale |
| NFS background exit and cleanup | TC133 | Per-PID waits, fd inheritance guard, client-first cleanup |

### 23. Final Correctness Findings
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| Linux-compatible 48-bit superblock union fallback | TC017, TC019, TC150 | `rootnid_8b == 0` selects `rootnid_2b` and low blocks |
| Extended inode signed-size boundary | TC151 | Bit-63 `i_size` fails before pager setup |
| Bounded compressed extent holes | TC152 | 5 GiB hole, one-byte pread and one-page mmap |
| 64-bit directory block search | TC153 | Multi-TiB Layout 0 provider returned repeated `EINTEGRITY` |

### 24. Review Fixes
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| Per-inode NFS replacement detection | TC154 | Same superblock, UUID, NID and content; changed raw inode |
| Explicit extent physical-address checked add | TC155 | Four-byte records with `pa + plen` overflow |
| Inode timestamp range validation | TC156 | Compact epoch overflow, signed `time_t`, compact/extended nanoseconds |

### 25. Independent Final Review
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| Explicit table global ordering | TC157 | 16/32-byte descending, duplicate, cross-branch rejection |
| Extended compressed `blocks_hi` | TC158 | Direct/file-handle allocation and FBT `va_bytes` |
| Special-vnode setattr combinations | TC159 | Size-only no-op and combined mutation rejection |
| Dot-omitted `OFF_MAX` cookie | TC160 | Both initial offsets return `EINTEGRITY` without advancement |
| Fatal `nm` failure | TC161 | Publication preservation, temp cleanup, post-shim rebuild |

### 26. Pre15 Test Foundation
| Feature | Test Cases | Coverage |
|---------|-----------|----------|
| G3 stable fixture migration | B01-g3-equivalence | Archived hash, canonical inventory, byte hash, expectation, repeat generation |
| Runner failure separation | B01-runner-selftest | Good, DUT mismatch, pre-target failure, SSH, QEMU exit, timeout, cleanup |
| Legacy xattr prefix fallback | TC162 | Primary legacy, explicit plain, packed, metabox, exact `EINTEGRITY` negatives |

Latest final-review results are recorded in
`tests/results/manual/2026-08-09T1804Z-final-review-independent/manual-test-report.md`.
TC010, TC060, and TC153 are resolved historical issues. The only approved
remaining gap is TC146's positive explicit mapped-payload fixture.