docs: trim, deduplicate, and restructure sidebar#5020
Conversation
Remove cookbook.md (all recipes duplicated dedicated pages). Trim best-practices to TUnit-specific tips (707→139 lines), philosophy padding (177→154), and performance questionable advice (574→422). Deduplicate await-assertions in troubleshooting, EF Core pattern in complex-test-infrastructure, and SharedType list in property-injection — each replaced with canonical links. Restructure sidebar: add Integrations and Comparing Frameworks sections, move parallelism under Writing Tests, move AOT under Running Tests, remove testcontext-interface-organization from nav. Clean filler language across intro, test-context, hooks-setup, arguments, and lifecycle. Fix stale versions in fsharp-interactive (0.20.16→1.6.0), filebased-csharp (0.*→1.*), and README links. Build verified: npm run build passes (onBrokenLinks: 'throw').
Documentation: Trim, Deduplicate, and Restructure SidebarThis is a well-executed documentation cleanup. The -1,845 / +155 net change is impressive without losing critical information. The restructured sidebar is meaningfully more intuitive. Overall this looks great -- a few things worth checking before merging: Potential Broken Anchor Referencecomplex-test-infrastructure.md now points to aspnet.md#per-test-schema-isolation-with-ef-core. The PR test plan notes npm run build passes, which catches broken page links via onBrokenLinks: 'throw'. However, Docusaurus only validates anchors by default if onBrokenAnchors is also set to 'throw'. Worth confirming the heading "Per-Test Schema Isolation with EF Core" (or equivalent) actually exists in aspnet.md -- if it does not, the link silently goes nowhere. testcontext-interface-organization Silently OrphanedThe page is removed from the sidebar nav but the file presumably still exists at its URL. If the content is superseded, deleting the file outright (or adding a redirect) would be cleaner than leaving an orphaned page. If it is being kept for SEO or deep links, that is fine -- but worth an explicit decision either way. Removing Inline Examples vs. Cross-ReferencesThe EF Core schema isolation example (84 lines) was the most complete worked example of that pattern in the repo. The replacement prose works only if the target aspnet.md section is genuinely as detailed. The same concern applies to property-injection.md replacing the SharedType bullet list with "See ClassDataSource for all sharing options." Cross-linking is better for maintenance, but only when the target is actually comprehensive. The test plan's unchecked "Visual review of sidebar structure in dev server" step is a good moment to spot-check these cross-references. Version Pinning in ExamplesThe fsharp-interactive.md and filebased-csharp.md examples were correctly updated from 0.20.16/0.* to 1.6.0/1.. Minor: pinning to a specific patch version (1.6.0) in docs will go stale on the next release. The wildcard form (1.) used in one of the file-based examples is more resilient -- consider using it consistently. Sidebar Restructure QualityThe new structure is genuinely better:
best-practices.md RenameRenaming to "Tips & Pitfalls" is a good signal about scope. The condensed content is high-quality and TUnit-specific. The removed content (test naming conventions, Method_Scenario_ExpectedBehavior patterns, one-assertion-per-behavior guidance) was generic advice that belongs in a general testing guide rather than TUnit-specific docs. Good call to cut it. Summary: This is ready to merge pending confirmation that the aspnet.md anchor for EF Core schema isolation exists. The rest of the tradeoffs are well-reasoned and the net result is a significantly more maintainable doc set. |
…sion wildcards - Move SharedType option list into class-data-source.md as canonical location, fixing circular reference where class-data-source linked to property-injection which linked back to class-data-source - Use version wildcards in fsharp-interactive.md code example to avoid going stale on each release (keep pinned version only in the "specify a specific version" example) - testcontext-interface-organization.md intentionally kept as unlisted page — useful for API migration, findable via search
There was a problem hiding this comment.
Documentation Cleanup Review
This is a well-executed docs overhaul. The net -1,684 lines is impressive and the restructured sidebar is meaningfully better. A few items worth addressing before merging:
Issue 1: Unverified Anchor Reference (Potential Silent Broken Link)
complex-test-infrastructure.md now points to:
aspnet.md#per-test-schema-isolation-with-ef-core
Docusaurus validates broken page links via onBrokenLinks: 'throw', but anchor validation (onBrokenAnchors) is a separate config that defaults to 'warn' or 'ignore' in many setups. If the heading ## Per-Test Schema Isolation with EF Core (or equivalent) doesn't exist in aspnet.md, the link silently resolves to the top of the page rather than failing the build.
Recommendation: Confirm this anchor exists in aspnet.md before merging. The test plan's unchecked "Visual review of sidebar structure in dev server" step is the right time to spot-check this.
Issue 2: testcontext-interface-organization Silently Orphaned
The page is removed from the sidebar nav (previously in "Migration Guides") but the file presumably still exists at its URL. Without a redirect:
- Any existing bookmarks silently 404
- Third-party links break
Recommendation: Either delete the file outright (or merge its content into an existing page), or add a Docusaurus redirect to the closest relevant page. If the content has been superseded, deleting is cleanest.
Issue 3: .NET 10 Treenode-Filter Tip Removed Without Replacement
performance.md removes this useful note:
> **Note**: With .NET 10 SDK or newer, you can use the simpler syntax:
> ```bash
> dotnet test --no-build --treenode-filter "/**[Category=Unit]"
> ```The /** wildcard syntax is a real ergonomic improvement for .NET 10 users — removing this without moving it to execution/test-filters.md or the CI/CD section is a loss.
Recommendation: Move this tip to execution/test-filters.md or the CI/CD section rather than discarding it.
Issue 4: F# Interactive — Unpinned Version in Examples
The old examples pinned #r "nuget: TUnit, 0.20.16" and the new form drops the version entirely:
#r "nuget: TUnit"
#r "nuget: TUnit.Assertions.Fsharp"Unpinned references are more maintainable (no stale version number), but F# interactive scripts with unpinned nuget packages resolve to the latest stable version at script evaluation time, which is actually the correct behavior for docs. However, if a user copies this and there's a prerelease package published, they could get an unexpected version.
This is a minor concern — the wildcard 1.* form used in filebased-csharp.md is a reasonable middle ground if consistency matters.
What's Working Well
Sidebar restructure: The split of "Lifecycle & Hooks" into "Setup & Cleanup", "Test Context & Output", and "Test Infrastructure" is a genuine UX improvement. Separating "Comparing Frameworks" from "Migration Guides" removes a significant source of confusion for users evaluating vs. migrating. Moving "Test Data" to the top of Writing Tests matches the natural authoring flow.
best-practices.md → "Tips & Pitfalls": The renamed, condensed version (707→139 lines) is much better. Cutting generic advice (test naming conventions, avoid-over-mocking patterns) that belongs in a general testing guide leaves only TUnit-specific gotchas. This is exactly the right scope for this page.
cookbook.md deletion: The cookbook was 777 lines of patterns that all had canonical homes. Removing the duplicate-and-stale copy and pointing to the authoritative sources is the right call — it eliminates a maintenance burden where the cookbook example could silently diverge from the dedicated page.
class-data-source.md SharedType list: Moving the SharedType inline list from property-injection.md to class-data-source.md is better canonicalization. The ClassDataSource page is the more natural home for this content.
troubleshooting.md trimming: The 91-line await-assertions FAQ is well-condensed to 7 lines + cross-reference — assuming assertions/awaiting.md covers the design rationale, migration steps, and common mistakes in detail.
Summary: Ready to merge pending: (1) confirming the aspnet.md EF Core anchor exists, and (2) deciding whether to delete testcontext-interface-organization.md or add a redirect. The .NET 10 filter tip is worth preserving somewhere rather than discarding.
Updated [TUnit](https://github.com/thomhurst/TUnit) from 1.17.36 to 1.18.0. <details> <summary>Release notes</summary> _Sourced from [TUnit's releases](https://github.com/thomhurst/TUnit/releases)._ ## 1.18.0 <!-- Release notes generated using configuration in .github/release.yml at v1.18.0 --> ## What's Changed ### Other Changes * refactor: convert 15 manual assertions to [GenerateAssertion] by @thomhurst in thomhurst/TUnit#5029 * Fix invisible chart labels on benchmark pages by @Copilot in thomhurst/TUnit#5033 * docs: fix position of `--results-directory` in documentation by @vbreuss in thomhurst/TUnit#5038 * fix: IsEquivalentTo falls back to Equals() for types with no public members by @thomhurst in thomhurst/TUnit#5041 * perf: make test metadata creation fully synchronous by @thomhurst in thomhurst/TUnit#5045 * perf: eliminate <>c display class from generated TestSource classes by @thomhurst in thomhurst/TUnit#5047 * perf: generate per-class helper to reduce JIT compilations by ~18,000 by @thomhurst in thomhurst/TUnit#5048 * perf: consolidate per-method TestSource into per-class TestSource (~27k fewer JITs) by @thomhurst in thomhurst/TUnit#5049 * perf: eliminate per-class TestSource .ctor JITs via delegate registration by @thomhurst in thomhurst/TUnit#5051 * feat: rich HTML test reports by @thomhurst in thomhurst/TUnit#5044 ### Dependencies * chore(deps): update tunit to 1.17.54 by @thomhurst in thomhurst/TUnit#5028 * chore(deps): update dependency polyfill to 9.13.0 by @thomhurst in thomhurst/TUnit#5035 * chore(deps): update dependency polyfill to 9.13.0 by @thomhurst in thomhurst/TUnit#5036 **Full Changelog**: thomhurst/TUnit@v1.17.54...v1.18.0 ## 1.17.54 <!-- Release notes generated using configuration in .github/release.yml at v1.17.54 --> ## What's Changed ### Other Changes * docs: restructure, deduplicate, and clean up documentation by @thomhurst in thomhurst/TUnit#5019 * docs: trim, deduplicate, and restructure sidebar by @thomhurst in thomhurst/TUnit#5020 * fix: add newline to github reporter summary to fix rendering by @robertcoltheart in thomhurst/TUnit#5023 * docs: consolidate hooks, trim duplication, and restructure sidebar by @thomhurst in thomhurst/TUnit#5024 * Redesign mixed tests template by @thomhurst in thomhurst/TUnit#5026 * feat: add IsAssignableFrom<T>() and IsNotAssignableFrom<T>() assertions by @thomhurst in thomhurst/TUnit#5027 ### Dependencies * chore(deps): update tunit to 1.17.36 by @thomhurst in thomhurst/TUnit#5018 * chore(deps): update actions/upload-artifact action to v7 by @thomhurst in thomhurst/TUnit#5015 * chore(deps): update dependency microsoft.testing.extensions.codecoverage to 18.5.1 by @thomhurst in thomhurst/TUnit#5025 **Full Changelog**: thomhurst/TUnit@v1.17.36...v1.17.54 Commits viewable in [compare view](thomhurst/TUnit@v1.17.36...v1.18.0). </details> [](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Summary
cookbook.md— every recipe duplicated a dedicated page (DI, WebAppFactory, mocking, exceptions)best-practices.md(707→139 lines, renamed "Tips & Pitfalls"),philosophy.md(177→154),performance.md(574→422, removed GC.Collect/early-exit advice)testcontext-interface-organizationfrom navintro.md,test-context.md,hooks-setup.md,arguments.md,lifecycle.mdfsharp-interactive.md(0.20.16→1.6.0),filebased-csharp.md(0.*→1.*),README.md(3 broken URLs)Net change: +155 / -1,845 lines across 17 files.
Test plan
npm run buildpasses indocs/(catches broken links viaonBrokenLinks: 'throw')