XQUIC Validate
Use the repository-wide scripts/validate.sh interface and the
validation specification.
Coverage Gate
Before running validation for a production behavior change, verify that the
diff contains:
- Unit coverage tied to the changed path.
- At least one happy-path unit test.
- At least one abnormal, rejection, boundary, or error-branch unit test.
- Endpoint-visible coverage for the happy path.
- Endpoint-visible abnormal coverage that proves the expected rejection,
error, close, or recovery behavior.
- A distinct, never-before-used and currently unreserved ID for each new
client-to-server case, allocated from the owning layer or module namespace
in the
validation specification.
- The new IDs recorded in the namespace registry in the same change.
When adding scripts/case_test.sh cases, give the two cases distinct
case_print_result names. Assert the observable client and server results
needed to prove the behavior. Reusing an unrelated test or case ID, or
asserting only that the process exited, is not sufficient. Active and retired
case IDs are both permanently unavailable for new behavior.
Workflow
Inspect the changed-file scope and preserve unrelated user changes.
Apply the Coverage Gate before treating validation as complete.
For every new case ID, refresh origin/main, check scripts/case_test.sh,
tests/test_client.c, tests/test_server.c, and their Git history. Require
no previous allocation and confirm the registry range matches the owning
protocol layer or module.
Query all open pull requests targeting main and inspect the exact
published head SHA for each pull request other than the current one. Require
the candidate numeric token to be absent from the three selector files.
Follow the complete fail-closed procedure in the validation specification;
an incomplete query is not proof that an ID is free.
During development, use a focused registered CUnit test for fast feedback:
XQC_TEST_NAME=<test-name> ./scripts/validate.sh test
For feature-gated paths, select the feature by manifest key:
./scripts/validate.sh test --feature <feature>
The script reads feature flags and feature unit tests from
harness/spec/harness-manifest.yml. Do not add feature-specific script
branches when manifest data is sufficient.
Before creating or updating a code pull request, clear the focused-test
selector and run the complete unit suite:
unset XQC_TEST_NAME
./scripts/validate.sh test
Require the emitted CUnit summary to show Ran == Total and Failed == 0.
Record the result as <Ran>/<Total> CUnit tests; CTest 1/1 alone is not
complete-unit-suite evidence.
Run targeted client-to-server commands only when the relevant blocks can be
executed directly and recorded without the legacy full case_test.sh suite.
Use XQC_BUILD_DIR=build ./scripts/validate.sh full only when explicitly
requested or when the change owner accepts the full-suite cost.
Require the complete unit suite to pass. For endpoint-visible behavior,
report targeted case results when available; otherwise report the case-test
gap instead of claiming local regression is complete.
Repeat the open-PR reservation scan for each new case ID after the tests
pass and immediately before PR submission or update. Record the snapshot
time, candidate IDs, number of heads checked, current PR exclusion, and
result.
Verify that include/xquic/xqc_configure.h and other generated artifacts
did not enter the source diff.
Report the changed scope, CUnit <Ran>/<Total> and failed counts, paired
unit-test names, endpoint coverage or gap status, paired case IDs and
namespaces when new cases are added, reservation snapshot, exact commands,
and results in ignored local evidence.
Summarize those current-head results in the repository
pull-request template. List
only each executed case ID and its concise behavior, then mark local
regression Complete or name concise failed/gap cases. Do not copy commands, test
function names, logs, namespace ranges, or reservation snapshots into the
PR body. Missing, stale, focused-only, or failed local evidence still does
not pass the gate.
After the PR or updated head is published, scan again with the current PR
included. On a duplicate, the lowest PR number keeps the ID; every later PR
must return to draft, mark local regression incomplete, reallocate, and
rerun this workflow.
Documentation-only changes may use link, format, and command-syntax checks
instead of inventing runtime tests. Validation-tooling changes require the
closest deterministic self-checks. State why runtime coverage is not
applicable.
Guardrails
- Do not add issue-specific validation modes, targets, paths, or flags.
- Do not hard-code one feature's validation path in
scripts/validate.sh;
add or update manifest feature data instead.
- Do not install packages, clone dependencies, or modify external services.
- Do not edit production code while acting only on a validation request.
- Stop after a failed build; diagnose it before running tests.
- Do not submit a code pull request with a missing happy-path or abnormal-path
unit test.
- Do not claim endpoint-visible coverage passed when the relevant case blocks
were not executed.
- Do not reuse an active or retired case ID, use an ID outside its documented
namespace, take an ID reserved by another open PR, or give the paired happy
and abnormal cases the same ID.
- Do not treat a failed or partial open-PR query as an empty reservation set.
- Do not keep a duplicate ID in the later-numbered PR after the
post-publication collision check.
- Do not use a focused test as pull-request evidence in place of the complete
local unit suite.
- Do not use the aggregate
CTest 1/1 result in place of the CUnit
<Ran>/<Total> and failed counts.
- Do not treat an environment blocker as a passing gate; keep the pull request
in draft or resolve the blocker before review.
- Keep raw logs under the ignored validation artifact directory.
- For task-local diagnosis and final evidence, use the run artifact contract
in
harness/spec/run-artifacts.md.
1---2name: validate3description: Enforce XQUIC test coverage and local validation gates. Use when code, build, or test changes need verification; before commit or pull request; or when asked to build, test, validate, or verify XQUIC. Requires paired happy-path and abnormal-path unit tests, the complete local unit suite, and explicit endpoint coverage or gap reporting for production behavior changes.4metadata:5 source: https://skillmd.com/skills/alibaba/validate6---78# XQUIC Validate910Use the repository-wide `scripts/validate.sh` interface and the11[validation specification](../../spec/validation.md).1213## Coverage Gate1415Before running validation for a production behavior change, verify that the16diff contains:17181. Unit coverage tied to the changed path.192. At least one happy-path unit test.203. At least one abnormal, rejection, boundary, or error-branch unit test.214. Endpoint-visible coverage for the happy path.225. Endpoint-visible abnormal coverage that proves the expected rejection,23 error, close, or recovery behavior.246. A distinct, never-before-used and currently unreserved ID for each new25 client-to-server case, allocated from the owning layer or module namespace26 in the27 [validation specification](../../spec/validation.md#client-to-server-case-id-namespace).287. The new IDs recorded in the namespace registry in the same change.2930When adding `scripts/case_test.sh` cases, give the two cases distinct31`case_print_result` names. Assert the observable client and server results32needed to prove the behavior. Reusing an unrelated test or case ID, or33asserting only that the process exited, is not sufficient. Active and retired34case IDs are both permanently unavailable for new behavior.3536## Workflow37381. Inspect the changed-file scope and preserve unrelated user changes.392. Apply the Coverage Gate before treating validation as complete.403. For every new case ID, refresh `origin/main`, check `scripts/case_test.sh`,41 `tests/test_client.c`, `tests/test_server.c`, and their Git history. Require42 no previous allocation and confirm the registry range matches the owning43 protocol layer or module.444. Query all open pull requests targeting `main` and inspect the exact45 published head SHA for each pull request other than the current one. Require46 the candidate numeric token to be absent from the three selector files.47 Follow the complete fail-closed procedure in the validation specification;48 an incomplete query is not proof that an ID is free.495. During development, use a focused registered CUnit test for fast feedback:5051 ```bash52 XQC_TEST_NAME=<test-name> ./scripts/validate.sh test53 ```54556. For feature-gated paths, select the feature by manifest key:5657 ```bash58 ./scripts/validate.sh test --feature <feature>59 ```6061 The script reads feature flags and feature unit tests from62 `harness/spec/harness-manifest.yml`. Do not add feature-specific script63 branches when manifest data is sufficient.64657. Before creating or updating a code pull request, clear the focused-test66 selector and run the complete unit suite:6768 ```bash69 unset XQC_TEST_NAME70 ./scripts/validate.sh test71 ```72738. Require the emitted CUnit summary to show `Ran == Total` and `Failed == 0`.74 Record the result as `<Ran>/<Total> CUnit tests`; `CTest 1/1` alone is not75 complete-unit-suite evidence.769. Run targeted client-to-server commands only when the relevant blocks can be77 executed directly and recorded without the legacy full `case_test.sh` suite.78 Use `XQC_BUILD_DIR=build ./scripts/validate.sh full` only when explicitly79 requested or when the change owner accepts the full-suite cost.8010. Require the complete unit suite to pass. For endpoint-visible behavior,81 report targeted case results when available; otherwise report the case-test82 gap instead of claiming local regression is complete.8311. Repeat the open-PR reservation scan for each new case ID after the tests84 pass and immediately before PR submission or update. Record the snapshot85 time, candidate IDs, number of heads checked, current PR exclusion, and86 result.8712. Verify that `include/xquic/xqc_configure.h` and other generated artifacts88 did not enter the source diff.8913. Report the changed scope, CUnit `<Ran>/<Total>` and failed counts, paired90 unit-test names, endpoint coverage or gap status, paired case IDs and91 namespaces when new cases are added, reservation snapshot, exact commands,92 and results in ignored local evidence.9314. Summarize those current-head results in the repository94 [pull-request template](../../../.github/pull_request_template.md). List95 only each executed case ID and its concise behavior, then mark local96 regression `Complete` or name concise failed/gap cases. Do not copy commands, test97 function names, logs, namespace ranges, or reservation snapshots into the98 PR body. Missing, stale, focused-only, or failed local evidence still does99 not pass the gate.10015. After the PR or updated head is published, scan again with the current PR101 included. On a duplicate, the lowest PR number keeps the ID; every later PR102 must return to draft, mark local regression incomplete, reallocate, and103 rerun this workflow.104105Documentation-only changes may use link, format, and command-syntax checks106instead of inventing runtime tests. Validation-tooling changes require the107closest deterministic self-checks. State why runtime coverage is not108applicable.109110## Guardrails111112- Do not add issue-specific validation modes, targets, paths, or flags.113- Do not hard-code one feature's validation path in `scripts/validate.sh`;114 add or update manifest feature data instead.115- Do not install packages, clone dependencies, or modify external services.116- Do not edit production code while acting only on a validation request.117- Stop after a failed build; diagnose it before running tests.118- Do not submit a code pull request with a missing happy-path or abnormal-path119 unit test.120- Do not claim endpoint-visible coverage passed when the relevant case blocks121 were not executed.122- Do not reuse an active or retired case ID, use an ID outside its documented123 namespace, take an ID reserved by another open PR, or give the paired happy124 and abnormal cases the same ID.125- Do not treat a failed or partial open-PR query as an empty reservation set.126- Do not keep a duplicate ID in the later-numbered PR after the127 post-publication collision check.128- Do not use a focused test as pull-request evidence in place of the complete129 local unit suite.130- Do not use the aggregate `CTest 1/1` result in place of the CUnit131 `<Ran>/<Total>` and failed counts.132- Do not treat an environment blocker as a passing gate; keep the pull request133 in draft or resolve the blocker before review.134- Keep raw logs under the ignored validation artifact directory.135- For task-local diagnosis and final evidence, use the run artifact contract136 in `harness/spec/run-artifacts.md`.