docs(testing): add Testing your document quickstart guide#116
Merged
Conversation
New docs/operations/test-your-document.md — a tutorial-style end-to-end recipe for protecting a custom document or template with automated tests. Five steps from "author the document" to "CI guards the shape on every PR", with a quick layer-selection table (smoke / layout snapshot / pixel-level visual). Complements the existing reference-style layout-snapshot-testing.md (deep dive on the public API, pipeline position, downstream-project adoption, CI policy). The new doc is the "where do I start" landing page; the existing doc remains the lookup-friendly reference. - README's "What can I do with this?" table row now links to BOTH docs so the quickstart is the first thing a new reader finds. - CHANGELOG entry under v1.6.8 Planned § Documentation. - Pixel-level visual gate is mentioned as "queued for v1.6.8 / v1.7.0 Track N" — accurate per the private taskboard; the guide does not block on N1 because everything it documents for the layout-snapshot path uses already-public API (LayoutSnapshotAssertions, LayoutSnapshotJson, the -Dgraphcompose.updateSnapshots flag).
2 tasks
DemchaAV
added a commit
that referenced
this pull request
Jun 1, 2026
…mple (final audit)
A second audit pass after promoting the site to the official
Pages target, addressing inconsistencies the first pass missed:
- components/Pipeline.tsx — the §03 "How it works" §01 step's
STEP1 source sample still used the legacy
`flow.addSection(s -> s.addParagraph(...).addTable(rows))` shape
with no section-name argument. Rewritten to mirror real DSL:
`page.addSection("Summary", s -> s.addParagraph(p -> p.text(...))
.addTable(t -> t.header(...).row(...)))`.
- components/Cta.tsx + components/PaperPage.tsx + lib/presets.tsx
— every CV demo persona was the placeholder name
"Avetik Demchaav" that drifted into the draft from earlier
iterations. Canonical author per `pom.xml`, `README`, javadocs
and the v1.6.6+ Maven Central release metadata is
**Artem Demchyshyn**. Replaced across the three locations
(Cta "Work with me" card, PaperCv CSS fallback for all three
layout variants, Playground CV preset code sample). Matching
email address pinned to `demchishynartem@gmail.com` — the same
one the Central artefact's POM developer block carries.
- components/Cta.tsx — "v2 quickstart" link pointed at
`docs/quickstart.md`, a file that does not exist in the repo
(a pre-existing dead link in the draft). Redirected to
`docs/operations/test-your-document.md` — the testing
quickstart guide that landed in v1.6.8 (#116). Link text
updated to "Testing quickstart" to match.
Verification: ./out static export still builds clean
(`next build` exits 0, 4 pages, 99.8 kB first-load JS).
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
1 participant
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.
Summary
First doc landing in the v1.6.8 cycle. Adds a tutorial-style
quickstart for the existing semantic-layout snapshot API, sibling
to the existing reference-style
docs/operations/layout-snapshot-testing.md.Came out of the v1.6.7 senior review session when surveying the
test/protection coverage of our presets and examples: the
semantic-layer story (
LayoutSnapshot+LayoutSnapshotAssertionsa "where do I start?" landing page for a developer who just
wrote their first custom template and wants to lock its shape
against engine refactors.
What the new doc covers
End-to-end recipe in five steps:
GraphCompose.document()...LayoutSnapshotAssertions.assertMatches(...)test nextto it
-Dgraphcompose.updateSnapshots=true./mvnw test; any drift fails the buildthe same PR
Plus a "when to use which layer" table for the three protection
tiers (smoke / layout snapshot / pixel-level visual). Mentions
that the pixel-level visual harness
(
PdfVisualRegression+ImageDiff) is currently test-onlyand is queued for promotion to public
com.demcha.compose.testing.visual.*as v1.6.8 / v1.7.0 Track N.What this PR does NOT touch
layout-snapshot-testing.md(the long reference) — untouched.It stays as the deep dive; the new quickstart links into it
whenever the reader needs more detail.
This doc just makes it more discoverable.
Why land it before Track N1
The doc covers what is already-public API today
(
LayoutSnapshotAssertions,LayoutSnapshotJson, the-Dgraphcompose.updateSnapshotsflag). The pixel-levelmention is forward-looking and accurate. No reason to gate the
discoverability win on N1 (promote
PdfVisualRegression); thatPR will simply add a sibling guide.
Test plan
./mvnw test -pl . -Dtest=VersionConsistencyGuardTest,DocumentationCoverageTest,DocumentationExamplesTest(doc guards expected to remain green — pure additions, no API touch).API (manual review — uses
GraphCompose.document(),DocumentSession,LayoutSnapshotAssertions.assertMatches,all stable from v1.6.0+).