Document testing facilities#272
Merged
sgerbino merged 4 commits intocppalliance:developfrom Apr 30, 2026
Merged
Conversation
New top-level section 7 (Testing Facilities) documents every public header under include/boost/capy/test/. The section mirrors section 6 (Stream Concepts) one-for-one so a reader who learned a concept can find its mock counterpart by predictable navigation. Pages (under doc/modules/ROOT/pages/7.testing/): * 7.intro - section overview, header-to-page map * 7a.drivers - run_blocking, fuse, thread_name * 7b.mock-streams - read_stream, write_stream, stream * 7c.mock-sources-sinks - read_source, write_sink * 7d.mock-buffer-concepts - buffer_source, buffer_sink * 7e.buffer-inspection - bufgrind, buffer_to_string Each page follows section 6's shape: brief lede, one == per type with code example and === subsections for nuance, an inline API table per type showing the constructor as a single declaration with defaults, a closing snippet that combines the page's types, a == Reference table, and a closing pointer to the next page. The fuse class is a pimpl backed by std::shared_ptr<state>, so by-value constructor arguments share fail-point machinery; this is documented in 7a and cross- referenced from each mock that takes fuse by value. Existing Examples (was 7) renumbered to 8 and Design (was 8) renumbered to 9. All cross-references updated. nav.adoc inserts the new section between Streams (6) and Examples (8).
Eight xrefs in `index.adoc` and `quick-start.adoc` used the old flat path style (e.g. `coroutines/tasks.adoc`) instead of the numbered prefix the rest of the site uses (`4.coroutines/4a.tasks.adoc`). Antora was emitting "target of xref not found" errors on every build. Updated all eight to point at the actual page paths. The ninth error was in `9k.Executor.adoc` (formerly `8k.Executor.adoc`), which linked to `../continuation-rationale.adoc` — that file is a markdown design note (`doc/continuation-rationale.md`), not an Antora page, so the xref could never resolve. Removed the broken link; the surrounding prose still describes what `continuation` is. Antora build now reports zero errors.
|
An automated preview of the documentation is available at https://272.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-04-30 19:01:57 UTC |
Four pages cited a `cat()` function that was never part of the public
buffer API. The Antora build did not flag these because the references
appeared inside `[source,cpp]` blocks (not xrefs), but readers following
the examples would hit a compilation error.
Fixes:
* `5a.overview.adoc` — removed the `Zero-Allocation Composition`
section; the conceptual point ("any composition of the above without
allocation") is preserved in the bullet list above and in
`5c.sequences.adoc`.
* `5c.sequences.adoc` — removed the `Zero-Allocation Composition`
section; `Heterogeneous Composition` already covers the same idea.
* `5e.algorithms.adoc` — rewrote the Zero-Copy I/O example to use
`std::array` directly, mirroring the Scatter/Gather example on the
same page.
* `8c.buffer-composition.adoc` — removed the exercise that referenced
`cat()`; the other two exercises remain.
|
GCOVR code coverage report https://272.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-04-29 21:33:06 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #272 +/- ##
========================================
Coverage 92.35% 92.35%
========================================
Files 168 168
Lines 9414 9414
========================================
Hits 8694 8694
Misses 720 720
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
|
GCOVR code coverage report https://272.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-04-30 19:12:09 UTC |
Audit of all 35 code snippets in 7.testing pages against actual headers
revealed structural bugs that were verified by compiling and running
each example. Fixes:
* 7a thread_pool snippet: replace nonexistent <boost/capy/thread_pool.hpp>
and pool.post(lambda) (which takes only `continuation&`) with the
idiomatic run_async(pool.get_executor())(coroutine) pattern.
* 7b/7c/7d "Putting It Together" snippets: add missing concept-header
includes (read_stream, read_source, write_sink, buffer_source,
buffer_sink) so the templated examples actually compile.
* 7b/7c/7d "Putting It Together" snippets: fix a structural bug where
mocks were constructed and asserted on outside the f.armed() lambda.
With armed running the body multiple times for fault injection, the
outside state was the last run's state, not the success run's. Move
mock construction and state assertions inside the lambda following
the canonical capy test pattern, with functions-under-test now
returning std::error_code so callers can guard with
`if(ec) co_return;`.
* 7c handle_request: read_source::read returns cond::eof on partial
fill; treat eof-with-data as success rather than bailing.
* 7d buffer_sink basic example: remove the dead `if(bufs.empty())
co_return;` check. prepare() always returns a 1-element span for a
non-empty input array.
* All "Returns ...eof" prose and table descriptions: standardize on
cond::eof spelling per error.hpp:32 ("Compare with cond::eof"), since
cond::eof is the user-side comparison value while error::eof is the
implementation's returned code. Both compare equal.
* Mock constructor signatures in tables: add `explicit` qualifier to
match the actual headers (read_stream, write_stream, read_source,
write_sink, buffer_source, buffer_sink, fuse(error_code)).
* Document write_some rollback semantics: write_stream::write_some and
write_sink::write_some roll back on expected-data mismatch and return
(test_failure, 0); call out the asymmetry with write_sink::write,
which leaves the partial write in place.
* Expand 7a's "armed() vs. inert()" subsection with a smoke-test-first
pattern showing the same test body under both modes, plus prose
explaining when each fits.
* 7e bufgrind: add prose explaining why snippets use f.inert (bufgrind
does not do I/O or consult a fuse, so a single pass is sufficient).
All snippets verified by compiling and running them through the test
suite during development.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.