Skip to content

Commit 2edc4ba

Browse files
author
unit-test-impl-leader
committed
docs(spec): English translation of 6 unit-test specs (FU-U-7)
Translates the 6 zh_cn specs to English under docs/unit_test_spec/: 00-overview-and-glossary.md 01-requirements-spec.md 02-current-architecture-and-targets.md 04-cmocka-framework-and-impl.md 06-test-cases-and-acceptance.md 99-review-report.md Same layout as freebsd_13_to_15_upgrade_spec/ (English at root, Chinese in zh_cn/). Tables, code blocks, file paths, IDs, and line numbers are preserved verbatim.
1 parent 6a8a0f6 commit 2edc4ba

6 files changed

Lines changed: 1701 additions & 0 deletions

‎docs/unit_test_spec/00-overview-and-glossary.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# 00 — Project Overview and Glossary
2+
3+
> Document version: v0.1 (2026-06-09 17:45 UTC+8)
4+
> Author: spec-author (drafted from Phase 2 three-track research material)
5+
> Scope: CMocka unit-test framework for the glue code (FF_HOST_SRCS) under
6+
> the `lib/` directory of F-Stack v1.26 (FreeBSD 15.0 port + DPDK 24.11.6 LTS)
7+
8+
---
9+
10+
## 1. Project Background
11+
12+
F-Stack is a user-space TCP/IP stack that ports the FreeBSD network stack into
13+
user space and delivers a high-performance data plane on top of DPDK. As of
14+
2026-06-09, F-Stack has completed two large-scale upgrades (FreeBSD 13.0 → 15.0
15+
and DPDK 23.11.5 → 24.11.6 LTS), yet **has never had a unit-test framework**:
16+
17+
- The `f-stack/` repository root contains no `tests/` / `test/` directory.
18+
- No `#ifdef TEST` / `#ifdef UNITTEST` guards exist in `lib/*.c`.
19+
- Existing runtime validation relies on (a) the helloworld primary stack
20+
bring-up + curl smoke test, (b) nginx_fstack multi-worker smoke runs, and
21+
(c) the phase-5b performance matrix.
22+
- Those are **integration tests**; covering pure functions, string handling,
23+
and protocol parsing in the lib glue layer through them is prohibitively
24+
expensive.
25+
26+
→ This project introduces, for the first time, **real unit testing** for the
27+
F-Stack lib layer (based on CMocka 1.1.7), starting from the easiest-to-reach
28+
glue code and building a sustainable, evolvable testing system step by step.
29+
30+
## 2. Project Goals
31+
32+
| ID | Goal | Phase |
33+
|---|---|---|
34+
| **G-A** | Establish a **CMocka unit-test framework spec** for the host-side glue code under F-Stack `lib/` (FF_HOST_SRCS, 11 files) | **Current task (spec phase)** |
35+
| **G-B** | Phase 2: scaffold the `tests/unit/` project + first hello-world test | Future |
36+
| **G-C** | Phase 3: land the P0 cases (`ff_ini_parser.c` + `ff_log.c`) | Future |
37+
| **G-D** | Phase 4: extend with P1 (`ff_host_interface.c` + `ff_epoll.c` + `ff_config.c` end-to-end) | Future |
38+
| **G-E** | Phase 5: P2 follow-up (DPDK-heavy files) + CI integration + coverage gating | Future |
39+
40+
**This task scope = G-A only**, producing 7 Chinese spec documents (plan +
41+
6 specs); no test code is written, `lib/*.c` is not modified, and
42+
`lib/Makefile` is left untouched.
43+
44+
## 3. Scope (In-Scope / Out-of-Scope)
45+
46+
### 3.1 In-Scope
47+
48+
- ✅ The **11 glue-code files** listed in FF_HOST_SRCS (see 02 §2)
49+
- ✅ Spec for the CMocka 1.1.7 framework integration approach
50+
- ✅ Spec for the `tests/unit/` directory structure + draft Makefile
51+
- ✅ Mock-strategy matrix for four classes of external dependencies
52+
(DPDK rte_* / pthread / epoll / printf)
53+
- ✅ First-batch P0 test-case draft (TC-U-*)
54+
- ✅ Unity → CMocka API mapping table (referencing the `c-unittest-expert.mdc`
55+
methodology)
56+
57+
### 3.2 Out-of-Scope
58+
59+
- ❌ Unit tests for KERN_SRCS (the kernel-subset port) — about 20 files
60+
(`ff_veth.c` / `ff_glue.c` / `ff_route.c` / `ff_kern_*.c` / `ff_subr_*.c` /
61+
`ff_syscall_wrapper.c`, etc.) which are essentially a FreeBSD-kernel
62+
subset. They are not directly host-compiled, the unit-test value is low,
63+
and the mocking effort would explode.
64+
- ❌ Integration tests (already covered by helloworld + nginx + vlan-test)
65+
- ❌ Performance tests (already covered by the phase-5b matrix)
66+
- ❌ Bare-metal environment tests (handled by the user)
67+
- ❌ CI integration (DP-U-C1, deferred to Phase 5)
68+
- ❌ Mutation testing (DP-U-C2, deferred to Phase 5)
69+
- ❌ English version of the spec (DP-U-2 decision: deferred until human audit
70+
of the Chinese version is complete)
71+
- ❌ Actual test code / Makefile delivery (belongs to Phase 2+ G-B)
72+
73+
## 4. Relationship to the Existing System
74+
75+
### 4.1 Relationship to the docs/ three-layer architecture
76+
77+
| Three-layer doc | Relationship to this task |
78+
|---|---|
79+
| `docs/01-LAYER1-ARCHITECTURE.md` | All 11 files of this task fall under the L1-listed `lib/ff_dpdk_*.c` + `lib/ff_config.c` + `lib/ff_*.c` glue layer; spec 02 uses L1 file paths as anchors |
80+
| `docs/02-LAYER2-INTERFACES.md` | The "non-static public API" list of this task maps 1:1 to the L2 interface contracts; specs 02 / 06 cite L2 function signatures |
81+
| `docs/03-LAYER3-FUNCTIONS.md` | The static-helper / inih-handler list of this task is cross-validated against the L3 function index |
82+
83+
**After the spec is complete, the commit phase appends minimal anchor lines**
84+
to L1 (the same pattern as dpdk-23-24 / vlan-test), but `docs/01-LAYER*.md`
85+
is **not** touched during this spec phase.
86+
87+
### 4.2 Relationship to existing spec projects
88+
89+
| Project | Time | Style | Reused |
90+
|---|---|---|---|
91+
| `freebsd_13_to_15_upgrade_spec/` | 2025-2026 | Full 9-doc style | Backup-directory naming style / commit template |
92+
| `dpdk_23_24_upgrade_spec/` | 2026-06-09 | **Lean 7-doc style** | **Reused by this task** |
93+
| `unit_test_spec/` (this task) | 2026-06-09 17:35 | Lean 7-doc style | — |
94+
95+
### 4.3 Relationship to the c-unittest-expert.mdc rule
96+
97+
`workspace/.codebuddy/rules/c-unittest-expert.mdc` is a **Unity-based** Chinese
98+
methodology rule. This task **reuses its methodology** (test naming /
99+
setup-teardown / assertion granularity / boundary coverage), but **maps every
100+
API to its CMocka form**. spec 04 §3 provides the **Unity → CMocka API
101+
mapping table** (≥15 rows).
102+
103+
## 5. Glossary
104+
105+
| Term | Definition |
106+
|---|---|
107+
| **CMocka** | A lightweight unit-test framework for C (v1.1.7 already installed via `dnf install libcmocka libcmocka-devel`); home page https://cmocka.org/. Features: built-in mock + setjmp subprocess isolation + group fixture. |
108+
| **FF_HOST_SRCS** | The host-side source-file list defined in `lib/Makefile` (lines 272-291 + 568-572), totaling 11 `.c` files compiled directly on the host — distinct from KERN_SRCS (the FreeBSD kernel-subset port). |
109+
| **glue code** | Code that sits between the user-space TCP/IP stack and the DPDK PMD in F-Stack — primarily the `lib/ff_dpdk_*.c` / `lib/ff_config.c` files — and is the test target of this task. |
110+
| **mock** | Replacing an external function called by the code-under-test with a CMocka `__wrap_*` (linker flag) or `mock()` macro to control its return value and verify its arguments. |
111+
| **fixture** | The setup/teardown closure of `cmocka_unit_test_setup_teardown`, used to prepare/clean per-test resources (e.g., temporary `.ini` files, fake `ff_global_cfg`, etc.). |
112+
| **assertion** | CMocka-provided macros such as `assert_int_equal` / `assert_string_equal` / `assert_non_null`, used to verify the output of code-under-test. |
113+
| **inih** | The BSD-licensed third-party INI parser (https://github.com/benhoyt/inih) embedded into `ff_ini_parser.c`; the foundation for F-Stack's configuration parsing. |
114+
| **handler** | The 11 `*_cfg_handler` functions (all static) in `ff_config.c`, callbacks under the inih `ini_handler` protocol used to parse each `[section] key=value`. |
115+
| **P0/P1/P2/P3** | Test-priority tiers: P0 = land immediately (highest ROI) / P1 = second batch (high ROI) / P2 = follow-up (medium ROI) / P3 = not yet tested (low ROI). |
116+
| **TC-U-x** | Unit-test-case ID, numbered in spec 06. |
117+
| **FR-U-x** | Functional-requirement ID (functional requirement, unit-test), numbered in spec 01. |
118+
| **NFR-U-x** | Non-functional-requirement ID, numbered in spec 01. |
119+
| **R-U-x** | Risk ID, numbered in spec 01. |
120+
| **DP-U-x** | Decision-point ID, numbered in spec 01 + plan §4. |
121+
| **G1-G4** | Acceptance gates, defined in spec 01 §8. |
122+
| **bounce** | Gate-keeper review-rejection mechanism, capped at 3 (DP-U-8); ≥4 writes ESCALATION-INFO.md. |
123+
124+
## 6. Key-Decision Summary (full detail in spec 01 §7)
125+
126+
| ID | Decision | Value |
127+
|---|---|---|
128+
| DP-U-1 | Directory naming | `docs/unit_test_spec/zh_cn/` |
129+
| DP-U-2 | Document language | Chinese (English deferred) |
130+
| DP-U-3 | Number of specs | 7 (lean, reused from dpdk_23_24 mode) |
131+
| DP-U-4 | Test framework | CMocka 1.1.7 |
132+
| DP-U-6 | Test directory | `f-stack/tests/unit/` |
133+
| DP-U-7 | Build system | Standalone GNU Makefile + pkg-config |
134+
| DP-U-11 | Scope | FF_HOST_SRCS 11 files; KERN_SRCS out-of-scope |
135+
| DP-U-12 (revised) | P0 | **`ff_ini_parser.c` + `ff_log.c`** (after target-prioritizer Phase 2 adjustment; the original plan listed ff_config.c, but its handlers are all static, so it was moved to P1) |
136+
137+
## 7. Deliverables (spec phase)
138+
139+
| # | File | Line budget | Status |
140+
|---|---|---|---|
141+
| 1 | `plan.md` | 354 ✓ | local-only ✓ |
142+
| 2 | `00-overview-and-glossary.md` (this file) | ≤200 | drafting |
143+
| 3 | `01-requirements-spec.md` | ≤250 | pending |
144+
| 4 | `02-current-architecture-and-targets.md` | ≤450 | pending |
145+
| 5 | `04-cmocka-framework-and-impl.md` | ≤500 | pending |
146+
| 6 | `06-test-cases-and-acceptance.md` | ≤450 | pending |
147+
| 7 | `99-review-report.md` | ≤350 | pending |
148+
149+
## 8. Workspace Mandatory Conventions (re-stated)
150+
151+
- Direct `rm/kill/chmod` is forbidden; everything must go through
152+
`/data/workspace/{rm_tmp_file,kill_process,chmod_modify}.sh`.
153+
- No guessing; every line citation must be measured against actual code, with
154+
the reviewer cross-checking ≥10 places.
155+
- Chinese spec; English version deferred until human audit completes.
156+
- Local commit only; no push.
157+
158+
---
159+
160+
**End of document (v0.1)**

0 commit comments

Comments
 (0)