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

Test Coverage Matrix - repo22

Overview

Manual test specifications for the implemented FreeBSD EROFS paths. A listed test case is a procedure, not proof that every environment has executed it; dated reports under tests/results/manual/ contain execution evidence.

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
• 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
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 suite is manual-only. tests/erofs_fixture.py, tests/prepare_error_fixtures.sh, tests/prepare_directory_fixtures.sh, tests/read_probe.c, and tests/readdir_probe.c prepare or observe explicit assertions; none is a TC runner. The former wrapper generators, integration runner, partial image preparer, environment PASS printer, and result collector were removed because their success output was not acceptance evidence.

Test Case Status

• Specifications TC000-TC161 are present exactly once.
• Execution checklist and result templates are present.
• Dated manual reports record qualified runs and real limitations.
• TC150-TC152 have final-module FreeBSD 15 evidence.
• TC153 has exact-source sparse-provider FreeBSD 15 evidence.
• TC154-TC156 have final-module FreeBSD 15 evidence.
• TC157-TC161 have independent final-source FreeBSD 15 evidence.
• Final result is 160 PASS and TC146 PARTIAL.
• Automated kernel regression/coverage infrastructure is not 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

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.