Add insta snapshot tests for structured tracing event output

[coderabbitai]

Background

PR #303 (closes #296) added comprehensive tracing instrumentation to the inline-wrapping token- and fragment-classification pipeline, including #[traced_test] event-emission tests and a proptest for UTF-8 safety.

The Testing (Compile-Time / Ui) check from the PR review identified one remaining gap: no insta snapshot tests assert the stable structure of the emitted tracing events (field names, message strings, level) for the token, fragment, and footnote classification paths.

Required work

Add snapshot tests (using insta) that capture and assert the structured output of at least the following tracing call sites:

• Fragment classification (fragment classified debug event in src/wrap/inline/fragment.rs)
• Footnote reference parsing (footnote reference parsed debug event in src/wrap/tokenize/parsing.rs)
• Link/image parsing (link or image parsed trace event in src/wrap/tokenize/parsing.rs)
• Span promotion (token_span trace events in src/wrap/inline/token_span.rs)

The snapshots should assert at minimum the event message string and the structured field names (token, kind, start, end, width) so that accidental removal of instrumentation is caught at review time.

Constraints

• Do not install a global tracing subscriber in library code.
• Use #[traced_test] (already a dev-dependency) combined with insta's assert_snapshot! for capture.
• Snapshots must be committed to the repository under snapshots/.

References

• PR Add observability for inline wrapping token classification (#296) #303
• Issue Add observability infrastructure for inline-wrapping token classification #296
• Raised by @leynos

[coderabbitai]

🔗 Related PRs

#276 - Cli matrix testing [merged]
leynos/tei-rapporteur#79 - Use named validation BDD scenarios (#34) [closed]
#280 - Keep GFM footnote references atomic (#277) [merged]
#295 - Couple opening brackets with following inline code spans (#293) [merged]
#301 - Keep GFM footnote references with preceding code and link spans (#299) [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Add crate-colocated #[cfg(test)] snapshot modules (integration tests cannot reach the internal functions) that drive each instrumented call site with tiny deterministic inputs.
• Capture tracing output through #[traced_test]'s logs_assert, normalise it via one shared helper to strip volatile prefixes, and lock message/level/field names with file-based insta snapshots committed under snapshots/.
• Snapshot the events that actually exist (correcting the ticket's non-existent token_span.rs and the debug-vs-trace level for link/image), so the tests fail loudly if instrumentation is removed or reshaped.

Design Choices

Design Choice 1: Where should the snapshot tests live, given the instrumented functions are crate-internal?

Options Considered:

1. Colocate #[cfg(test)] snapshot modules inside src/ alongside the existing tracing tests, wired via #[path = "…"] mod …;.
2. Widen the target functions to pub and add integration snapshot tests under tests/wrap/.

Chosen Option: 1

Rationale: Integration tests under tests/ cannot reach pub(super)/pub(in …) functions without widening their visibility (scope creep the ticket does not request). Keep the functions internal and colocate the tests, matching the existing predicate_tracing_tests.rs/span_helper_tracing_tests.rs wiring and avoid gratuitous visibility changes.

Design Choice 2: How should the full formatted event text be captured for snapshotting when #[traced_test] only exposes a boolean logs_contain?

Options Considered:

1. Use the logs_assert(|lines: &[&str]| …) helper injected by #[traced_test] to copy the captured lines into an owned buffer, then snapshot that buffer.
2. Install a bespoke scoped subscriber (tracing::subscriber::with_default) writing to an in-memory buffer with a fixed format.

Chosen Option: 1

Rationale: The ticket mandates #[traced_test], but its documented helper only checks substrings; the full captured text must be reached another way. This option honours the explicit #[traced_test] constraint and reuses the already-installed per-test subscriber; volatile prefixes are removed by a normalisation helper so snapshots stay deterministic.

Design Choice 3: What are the real "span promotion" call sites, given the ticket cites a non-existent src/wrap/inline/token_span.rs?

Options Considered:

1. Snapshot the actual determine_token_span grouped date sequence (trace, src/wrap/inline.rs) and matched date sequence (debug, src/wrap/inline/span_helpers.rs) events.
2. Create a new token_span.rs to match the ticket wording.

Chosen Option: 1

Rationale: No token_span.rs exists; the promotion events live in src/wrap/inline.rs and src/wrap/inline/span_helpers.rs. Snapshot the events that genuinely exist; do not invent a module. Note also that link or image parsed is a debug! event, not trace! as the ticket states — snapshot the real level.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Establish a shared tracing-capture snapshot harness

Provide a single, test-only normalisation helper so every snapshot test captures tracing output in an identical, deterministic form. This isolates the one piece of shared logic (line filtering and volatile-prefix stripping) and keeps each subsequent test file thin.

Task 1: Create the capture-normalisation helper

Add a #[cfg(test)] support module that turns raw captured log lines into stable snapshot text.

• Create a new test-only module in the wrap module tree, e.g. src/wrap/tracing_snapshot_support.rs.
• Expose one function, roughly normalise_event_lines(lines: &[&str], message: &str) -> String, that retains only lines containing the target message, strips any leading timestamp/volatile prefix so runs are reproducible, trims trailing whitespace, and joins the survivors with newlines.
• Keep the level token (DEBUG/TRACE), target path, message, and structured fields intact — these are exactly what the snapshots must lock.
• Document the intended usage in a short module comment: call it from inside a #[traced_test] function via the injected logs_assert closure, copying the result into an owned buffer for insta::assert_snapshot!.

Task 2: Register the helper under #[cfg(test)]

Wire the new module so both wrap/inline and wrap/tokenize children can use it.

• In the wrap module root (src/wrap.rs or src/wrap/mod.rs), add #[cfg(test)] pub(crate) mod tracing_snapshot_support;.
• Confirm visibility allows the colocated child test modules in wrap/inline and wrap/tokenize to import it.

🤖 Prompt for AI agents

Implement the shared tracing-capture snapshot harness that every subsequent
snapshot test will reuse. Goal: a single deterministic normalisation helper for
raw log lines.

- Create a new test-only module `src/wrap/tracing_snapshot_support.rs`, gated by
`#[cfg(test)]`.
- Expose one function, roughly `normalise_event_lines(lines: &[&str], message:
&str) -> String`, that: retains only lines containing the target `message`;
strips any leading timestamp/volatile prefix for reproducibility; trims trailing
whitespace; joins survivors with newlines.
- Preserve the level token (DEBUG/TRACE), target path, message, and structured
fields intact in the output — these are exactly what must be locked by later
snapshots.
- Add a short module comment documenting intended usage: call from inside a
`#[traced_test]` function via the injected `logs_assert` closure, copying the
result into an owned buffer before passing to `insta::assert_snapshot!`.
- Register the module in the wrap module root (`src/wrap.rs` or
`src/wrap/mod.rs`) as `#[cfg(test)] pub(crate) mod tracing_snapshot_support;`.
- Verify visibility permits the colocated child test modules under `wrap/inline`
and `wrap/tokenize` to import and use this helper.

Phase 2: Snapshot the tokenize parsing events

Lock the structure of the two parsing events. Both are reachable through parse_link_or_image with tiny deterministic inputs already proven by the existing parsing_tests.rs.

Task 1: Add colocated parsing snapshot tests

Create a new snapshot-test file for the footnote and link/image events and wire it into parsing.rs.

• Add src/wrap/tokenize/parsing_tracing_snapshots.rs and register it with #[path = "parsing_tracing_snapshots.rs"] mod parsing_tracing_snapshots; inside the existing #[cfg(test)] region of src/wrap/tokenize/parsing.rs.
• Use #[traced_test] per test. For footnote reference parsed, drive parse_link_or_image("[^4] tail", 0); for link or image parsed, drive parse_link_or_image("[link](url)", 0).
• Inside each test, capture the lines via logs_assert, feed them through normalise_event_lines filtered by the event message, and snapshot the result with insta::assert_snapshot! using an explicit, descriptive name.
• Rely on insta's default snapshot_path (a snapshots/ directory beside the test file, i.e. src/wrap/tokenize/snapshots/); set prepend_module_to_snapshot => false via insta::with_settings! for clean, flat snapshot names — mirroring the flat-name convention used across tests/wrap/*_snapshots.rs.
• The resulting snapshots must show the message string, the level, and the field names actually emitted (token_length; token_length + is_image).

Task 2: Generate and commit the parsing snapshots

Produce the reviewable .snap artefacts.

• Run the tokenize tests with INSTA_UPDATE=always (or cargo insta review) to materialise the .snap files under src/wrap/tokenize/snapshots/.
• Inspect each generated snapshot to confirm no volatile timestamp survived normalisation, then commit the .snap files (never the .snap.new files).

🤖 Prompt for AI agents

Implement snapshot tests for the two tokenize parsing tracing events, reusing
the Phase 1 helper. Goal: lock message, level, and field names for `footnote
reference parsed` and `link or image parsed`.

- Create `src/wrap/tokenize/parsing_tracing_snapshots.rs` and register it inside
the existing `#[cfg(test)]` region of `src/wrap/tokenize/parsing.rs` via `#[path
= "parsing_tracing_snapshots.rs"] mod parsing_tracing_snapshots;`.
- For each event, write a `#[traced_test]` test: drive
`parse_link_or_image("[^4] tail", 0)` to fire `footnote reference parsed`; drive
`parse_link_or_image("[link](url)", 0)` to fire `link or image parsed`.
- Inside each test, capture lines via `logs_assert`, pass them through
`normalise_event_lines` filtered on the relevant message, and call
`insta::assert_snapshot!` with an explicit, descriptive snapshot name.
- Use insta's default `snapshot_path` (`snapshots/` beside the test file, i.e.
`src/wrap/tokenize/snapshots/`) and set `prepend_module_to_snapshot => false`
via `insta::with_settings!` to keep snapshot names flat, matching the convention
in `tests/wrap/*_snapshots.rs`.
- Confirm the snapshots expose the message string, the level, and the actual
field names (`token_length` for the footnote event; `token_length` and
`is_image` for the link/image event).
- Generate the `.snap` files by running the tokenize tests with
`INSTA_UPDATE=always` (or `cargo insta review`), inspect them to ensure no
volatile timestamp leaked through, and commit the `.snap` files only (never
`.snap.new`).

Phase 3: Snapshot the inline fragment and span-promotion events

Lock the remaining three events: fragment classification and the two date-sequence promotion events.

Task 1: Add the fragment-classification snapshot

Capture the fragment classified debug event structure.

• Add the snapshot test either to the existing #[cfg(test)] tests block in src/wrap/inline/fragment.rs or to a new colocated fragment_tracing_snapshots.rs wired via #[path = …] mod …; under its #[cfg(test)] region.
• Under #[traced_test], construct an InlineFragment/classify a fragment with a fixed short input so token, truncated, and kind are deterministic.
• Capture, normalise on the fragment classified message, and snapshot. The snapshot must expose the token and kind field names required by the ticket (plus truncated).

Task 2: Add the span-promotion snapshots

Capture the real promotion events in src/wrap/inline.rs and src/wrap/inline/span_helpers.rs.

• Extend src/wrap/inline/span_helper_tracing_tests.rs (or add a sibling span_promotion_tracing_snapshots.rs, wired the same way) reusing the existing date_tokens fixture (["25th", " ", "December", " ", "2025"]).
• Under #[traced_test], call determine_token_span(&date_tokens, 0) to fire determine_token_span grouped date sequence (fields start/end/width) and, via the same path, matched date sequence (fields start/end/pattern).
• Produce one focused snapshot per message by filtering with normalise_event_lines, so each snapshot locks a single event's fields and level. These cover the ticket's start/end/width field requirements.

Task 3: Generate snapshots and validate the whole suite

Materialise the inline snapshots and confirm the full test run is green.

• Regenerate the inline .snap files (INSTA_UPDATE=always / cargo insta review) under src/wrap/inline/snapshots/, inspect, and commit them.
• Run cargo test and cargo insta test --unreferenced=reject (or equivalent) to ensure no stray or unreferenced snapshots remain, and that the new tests pass deterministically on repeat runs.

🤖 Prompt for AI agents

Implement snapshot tests for the three remaining inline events: fragment
classification and the two span-promotion events. Goal: lock message, level, and
field names for `fragment classified`, `determine_token_span grouped date
sequence`, and `matched date sequence`.

- For the fragment event, add the snapshot test either inside the existing
`#[cfg(test)]` block in `src/wrap/inline/fragment.rs` or in a new colocated
`fragment_tracing_snapshots.rs` wired via `#[path = …] mod …;` under its
`#[cfg(test)]` region. Under `#[traced_test]`, construct/classify an
`InlineFragment` with a fixed short input so `token`, `truncated`, and `kind`
are deterministic; capture, normalise on the `fragment classified` message, and
snapshot, ensuring `token`, `kind`, and `truncated` fields are exposed.
- For the span-promotion events, extend
`src/wrap/inline/span_helper_tracing_tests.rs` (or add a sibling
`span_promotion_tracing_snapshots.rs` wired the same way), reusing the existing
`date_tokens` fixture (`["25th", " ", "December", " ", "2025"]`). Under
`#[traced_test]`, call `determine_token_span(&date_tokens, 0)` to fire
`determine_token_span grouped date sequence` (fields `start`/`end`/`width`) and
`matched date sequence` (fields `start`/`end`/`pattern`) via the same path.
Produce one focused snapshot per message using `normalise_event_lines`, so each
snapshot locks a single event's fields and level.
- Regenerate the inline `.snap` files under `src/wrap/inline/snapshots/` using
`INSTA_UPDATE=always` (or `cargo insta review`), inspect them, and commit the
`.snap` files.
- Run `cargo test` and `cargo insta test --unreferenced=reject` (or equivalent)
to confirm no stray or unreferenced snapshots remain and that all new tests pass
deterministically on repeat runs.

Research

mdtablefix is a single Rust crate whose inline-wrapping pipeline lives under src/wrap/. Tracing instrumentation is emitted at several call sites: src/wrap/inline/fragment.rs (fragment classified, fields token/truncated/kind), src/wrap/tokenize/parsing.rs (footnote reference parsed, field token_length; link or image parsed, fields token_length/is_image), and the span-promotion path in src/wrap/inline.rs (determine_token_span grouped date sequence, fields start/end/width) backed by src/wrap/inline/span_helpers.rs (matched date sequence, fields start/end/pattern). The repo-wide convention captures tracing output with tracing_test::traced_test + logs_contain boolean assertions; insta (1.47) is used elsewhere only for wrap-output snapshots. The functions under test are crate-internal (pub(super)/pub(in crate::wrap::inline)), so tests exercising them must be colocated inside src/ as #[cfg(test)] modules, not in tests/. No token_span.rs file exists."

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the shared tracing-capture snapshot harness that every subsequent
snapshot test will reuse. Goal: a single deterministic normalisation helper for
raw log lines.

- Create a new test-only module `src/wrap/tracing_snapshot_support.rs`, gated by
`#[cfg(test)]`.
- Expose one function, roughly `normalise_event_lines(lines: &[&str], message:
&str) -> String`, that: retains only lines containing the target `message`;
strips any leading timestamp/volatile prefix for reproducibility; trims trailing
whitespace; joins survivors with newlines.
- Preserve the level token (DEBUG/TRACE), target path, message, and structured
fields intact in the output — these are exactly what must be locked by later
snapshots.
- Add a short module comment documenting intended usage: call from inside a
`#[traced_test]` function via the injected `logs_assert` closure, copying the
result into an owned buffer before passing to `insta::assert_snapshot!`.
- Register the module in the wrap module root (`src/wrap.rs` or
`src/wrap/mod.rs`) as `#[cfg(test)] pub(crate) mod tracing_snapshot_support;`.
- Verify visibility permits the colocated child test modules under `wrap/inline`
and `wrap/tokenize` to import and use this helper.
===============================================================================

Task: 2

Implement snapshot tests for the two tokenize parsing tracing events, reusing
the Phase 1 helper. Goal: lock message, level, and field names for `footnote
reference parsed` and `link or image parsed`.

- Create `src/wrap/tokenize/parsing_tracing_snapshots.rs` and register it inside
the existing `#[cfg(test)]` region of `src/wrap/tokenize/parsing.rs` via `#[path
= "parsing_tracing_snapshots.rs"] mod parsing_tracing_snapshots;`.
- For each event, write a `#[traced_test]` test: drive
`parse_link_or_image("[^4] tail", 0)` to fire `footnote reference parsed`; drive
`parse_link_or_image("[link](url)", 0)` to fire `link or image parsed`.
- Inside each test, capture lines via `logs_assert`, pass them through
`normalise_event_lines` filtered on the relevant message, and call
`insta::assert_snapshot!` with an explicit, descriptive snapshot name.
- Use insta's default `snapshot_path` (`snapshots/` beside the test file, i.e.
`src/wrap/tokenize/snapshots/`) and set `prepend_module_to_snapshot => false`
via `insta::with_settings!` to keep snapshot names flat, matching the convention
in `tests/wrap/*_snapshots.rs`.
- Confirm the snapshots expose the message string, the level, and the actual
field names (`token_length` for the footnote event; `token_length` and
`is_image` for the link/image event).
- Generate the `.snap` files by running the tokenize tests with
`INSTA_UPDATE=always` (or `cargo insta review`), inspect them to ensure no
volatile timestamp leaked through, and commit the `.snap` files only (never
`.snap.new`).
===============================================================================

Task: 3

Implement snapshot tests for the three remaining inline events: fragment
classification and the two span-promotion events. Goal: lock message, level, and
field names for `fragment classified`, `determine_token_span grouped date
sequence`, and `matched date sequence`.

- For the fragment event, add the snapshot test either inside the existing
`#[cfg(test)]` block in `src/wrap/inline/fragment.rs` or in a new colocated
`fragment_tracing_snapshots.rs` wired via `#[path = …] mod …;` under its
`#[cfg(test)]` region. Under `#[traced_test]`, construct/classify an
`InlineFragment` with a fixed short input so `token`, `truncated`, and `kind`
are deterministic; capture, normalise on the `fragment classified` message, and
snapshot, ensuring `token`, `kind`, and `truncated` fields are exposed.
- For the span-promotion events, extend
`src/wrap/inline/span_helper_tracing_tests.rs` (or add a sibling
`span_promotion_tracing_snapshots.rs` wired the same way), reusing the existing
`date_tokens` fixture (`["25th", " ", "December", " ", "2025"]`). Under
`#[traced_test]`, call `determine_token_span(&date_tokens, 0)` to fire
`determine_token_span grouped date sequence` (fields `start`/`end`/`width`) and
`matched date sequence` (fields `start`/`end`/`pattern`) via the same path.
Produce one focused snapshot per message using `normalise_event_lines`, so each
snapshot locks a single event's fields and level.
- Regenerate the inline `.snap` files under `src/wrap/inline/snapshots/` using
`INSTA_UPDATE=always` (or `cargo insta review`), inspect them, and commit the
`.snap` files.
- Run `cargo test` and `cargo insta test --unreferenced=reject` (or equivalent)
to confirm no stray or unreferenced snapshots remain and that all new tests pass
deterministically on repeat runs.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!