Repository navigation
Restructure docs sidebar and simplify page titles - #42
Merged
Merged
Conversation
Group the flat sidebar into Introduction / Learn / Browser Tests / Comparisons / Reference categories, modeled after the Vitest guide. Drop SEO-stuffed titles so each page's title, H1, and sidebar entry match; keep search keywords in the description frontmatter (rendered as <meta name="description">). Use sidebar_label only where the sidebar entry should be shorter than the page title (Playwright, Rails, vs Pytest, vs RSpec, vs Minitest). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Rename the two Browser Tests pages from generic tool/framework names (Playwright, Rails) to scenario-driven titles that say what the page helps you do. This anticipates a future "Test a Rails app in Docker" page so the three sit naturally side by side. - Playwright page: "Test a remote site" - Rails page: "Test a Rails app locally" Drop the now-redundant sidebar_label entries since the new titles are already short enough for the sidebar. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Playwright page is the entry point of the Browser Tests category — it answers "why does this exist?" before the Quick Start. Rename it from a scenario title to a Why-style title that mirrors "Why Smartest" in Introduction, matching how Vitest pairs "Why Vitest" with "Why Browser Mode". Add a 4-line summary at the top, drawn from the dev.to article, that positions Smartest as making Ruby browser testing *smarter*, not just slightly nicer — pytest-style fixtures replace scattered RSpec/Minitest setup so the Playwright lifecycle is expressed directly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous summary opened with a critique of mainstream Ruby browser
testing, which buried the actual reason Smartest exists: it follows the
move Playwright Test made — choosing a dedicated runner over a Jest
plugin because browser testing is a different domain from unit testing.
Reframe so that inspiration leads, and the Ruby implication ("rebuild
the runner around pytest-style fixtures") follows from it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The page used to break flow with a "Why It Feels Like Playwright Test Fixtures" section between the intro and the Quick Start, which was disorienting for someone who had never tried browser testing with this library. Reorganize so a first-time reader gets a single Why up front, goes straight into the four-step scaffold, and only then meets the internals. - Drop the "Why It Feels Like Playwright Test Fixtures" section. The Playwright Test inspiration is already covered by the new Why intro, and the lifecycle bullets are restated alongside the actual fixture code in the "Browser lifecycle fixture" subsection. - Replace the old transition sentence with a practical bridge: "in practice you stay in Ruby … the four steps below take you from zero to a passing browser test." - Rename "Customization Points" to "How it works" so the second half of the page reads as an explanation of the scaffold rather than as advanced customization. - Reword the opening to "Smartest is invented to make Ruby browser testing smarter". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous intro just said "Smartest can run Rails browser tests against
your Rails test environment." That doesn't speak to the audience most likely
to land on this page: Rails engineers whose existing system-test suite is
flaky and hard to customize.
Rewrite the opening as a 4-sentence pitch that:
1. credits Rails system tests as a wonderful idea for edge-case browser
testing — FactoryBot, ActiveRecord, Rails helpers shaping state from Ruby
2. names the two operational problems that surface over time — Capybara is
hard to customize beyond its defaults, and the architecture tends to
produce flaky tests
3. positions Smartest as a Capybara-independent replacement built on
Playwright and pytest-style fixtures
4. reassures the reader that it coexists with existing system tests, so
migration can be gradual rather than a rewrite
Also update the page description so search snippets surface the same framing
("Capybara-independent ... coexists ... gradual migration").
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Capybara is the existing answer for Rails browser testing, so engineers considering Smartest most often arrive comparing it against Capybara — not against RSpec or Minitest. Add a dedicated comparison page so that audience can self-serve. The page is structured around two questions an engineer feeling operational pain actually asks: - "Should I migrate my login-form test?" → no, Capybara is great at short synchronous flows and there is no leverage to gain. - "Should I migrate my flaky modal/Turbo/SPA test?" → yes, the standard escape hatch (capybara-playwright-driver's with_playwright_page) adds a nested-callback layer that gets disproportionate fast, while in Smartest the same scenario is a flat sequence against a Playwright Page supplied by the page: fixture. The intro cites the Zenn article on with_playwright_page friction. The body follows the vs RSpec / vs Minitest layout: At a Glance table, concrete code-side-by-side comparisons, a DSL reference table, setup and stubbing, fit criteria, and a coexistence/migration section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two related changes that future docs PRs should not have to rediscover:
documentation/AGENTS.md (new)
Capture the framing and structural decisions made while restructuring the
site:
- what Smartest is for (smarter Ruby browser testing, not a nicer
RSpec) so individual pages do not have to re-establish it
- the sidebar shape (Introduction / Learn / Browser Tests /
Comparisons / Reference) and why
- per-page primary purpose for all 15 pages
- the title / sidebar_label / description split, and the SEO-stuffing
mistake we have already corrected
- the tone conventions (one Why per page, scenario titles, first-time
reader flow)
- an explicit overlap warning for "Test a Rails app locally" and
"vs Capybara": when editing one, read the other in the same change
and verify roles do not blur into duplication
AGENTS.md
Point the root agent instructions at documentation/AGENTS.md so editorial
decisions are loaded once, not re-derived per change.
documentation/docs/smartest-vs-capybara.md
Drop the citation to a specific Zenn article on with_playwright_page
friction. The point holds independently — the friction is widely
observed, not unique to one writeup — and the citation gave that one
article disproportionate authority. Replace with a direct claim
("the resulting nested-callback style feels disproportionate when all
you wanted was a slightly more stable browser test").
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "System" qualifier is redundant — system tests are the only context the class is used in, and the class is application-scoped. Rename the example class and the matching example file path so documentation does not push the verbose name on readers writing their first fixture. - ApplicationSystemFixture -> ApplicationFixture - smartest/fixtures/application_system_fixture.rb -> smartest/fixtures/application_fixture.rb Affects rails-browser-tests.md and smartest-vs-capybara.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This branch was successfully deployed
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
<title>,<h1>, and sidebar entry match (e.g.Pytest-style Fixtures in Ruby→Fixtures). Search keywords stay in thedescriptionfrontmatter, which Docusaurus renders as<meta name="description">.sidebar_labelonly where the sidebar entry should be shorter than the page title (Playwright, Rails, vs Pytest, vs RSpec, vs Minitest).intro.mdafter renaming the H1 (Smartest→Why Smartest).Sidebar before / after
Test plan
npm run buildpasses indocumentation/npm run serveverified via Playwright: page<title>isFixtures | Smartest, sidebar shows the new category structure, breadcrumb isHome > Learn > Fixtures, prev/next nav uses the new labels🤖 Generated with Claude Code