Repository navigation
feat: responsive testing with named viewports and an overlay sidebar - #445
Merged
Merged
Conversation
Design for #444: named viewports, tagging tests with { viewport }, the defaultViewport escape hatch for desktop-first suites, Run All per width, and the overlay sidebar with a run pill on small screens.
Tests can declare the viewport they were written for, and Run All only runs
the ones matching the current window width:
twd({ viewports: { mobile: { maxWidth: 767 }, desktop: { minWidth: 1024 } },
defaultViewport: 'desktop' })
it('opens burger menu', { viewport: 'mobile' }, async () => { ... })
- defineViewports() registry on window, shared by every twd-js copy, also
exposed as viewports/defaultViewport on initTWD and the Vite plugin.
- describe/it (and .only/.skip) accept options as the second argument; the
two-argument form is unchanged. Matching uses matchMedia, like app CSS.
- The runner fixes the run set at start, applies .only inside it, and fires
twd:run-start / twd:test-end / twd:run-end window events.
- executeTests({ viewport }) for the upcoming twd-cli viewport loop.
- Sidebar: live viewport chip, Run All label naming the viewport, a greyed
(AA contrast, never opacity) Other viewports group with badges, and a
warning log when a test runs outside its viewport.
- Below 768px of room the sidebar overlays the app instead of pushing it,
hides during runs behind a progress pill, and never switches mode mid-run.
Projects that declare no viewports keep today's behavior, except that small
windows now get the overlay instead of a squeezed page.
Refs #444
twd-test-app declares mobile and desktop viewports and gets a small responsive test file to try the sidebar while resizing. The mock-sw.js copies in every example are regenerated from the current build (v1.13.0).
The window width lived in the viewport state at the top of the sidebar, so every resize event re-rendered it and rebuilt the viewport partition. Only the chip and the other-viewports hint read the width now, and the push or overlay mode is a derived boolean. Also move Responsive Testing after Module Mocking in the docs menu and the llms files.
… them Moving them to an "Other viewports" group at the bottom took a test away from its siblings and repeated the suite name. They now keep their place in the describe, greyed and badged, and a suite whose tests are all for another viewport is greyed and starts collapsed.
The header stacked run buttons, chip, totals, speed, mock rules and search, which was a lot on a narrow sidebar. The mock rules button now sits behind a mockRules option, false by default, like search and pace. The version moves to the viewport chip row, which frees room next to the run buttons.
The chip right below already names the viewport, and the suffix made the button wrap on narrow sidebars.
The native arrow ignores the select's padding and sits against the border. It is hidden and replaced by the chevron the suites use.
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
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.
Closes part of #444 (twd-js only; the twd-cli viewport loop comes later).
What
Tests can declare the viewport they were written for, and Run All only runs the tests matching the current window width. The browser window is the selector: resize it (or use DevTools device mode) to switch.
Both options are optional. Without them nothing changes, except that small windows now get the overlay sidebar instead of a squeezed page (the bug in #444).
Runner
describe/it/.only/.skipaccept options as the second argument. The two-argument form is unchanged.describeviewport; a test-level value replaces it. Untagged tests run everywhere unlessdefaultViewportis set.window.matchMedia(falls back toinnerWidthwithout it), the same rule the app's CSS follows..onlyapplies inside the matching set, so an out-of-viewport.onlydoes not suppress the rest. The play button always runs.twd:run-start{ total },twd:test-end{ status },twd:run-end(always fired).executeTests({ viewport })inrunner-ci, ready for twd-cli.Sidebar
mobile · 390px). The Run All label stays as it is.describe, greyed with a badge naming their viewport. Adescribewhose tests are all for another viewport is greyed as a whole and starts collapsed. The grey is an AA-contrast muted color, never opacity, and the badge and accessible names carry the same information. Totals count the matching tests only.Lighter header
Rules: 0/0 triggered) is now hidden by default. A newmockRulesoption oninitTWD, thetwd()plugin andTWDSidebarbrings it back, followingsearchandpace.Written for desktop (min 1024px). Ran at 390px, so layout differences are expected.<html>margin, widthmin(sidebar width, 100vw - 56px)so the app always peeks out.TWD 2/3 ✓1 ✗0+ Show) and restores it at the end, scrolled to the first failure. Works for twd-relay runs too, via the window events. Never hides in push mode, and the layout mode never switches mid-run.viewportOtherText,viewportBadgeBg.Also
viewports/defaultViewport.specs/2026-11-19-responsive-testing-design.md.examples/twd-test-appdeclares viewports and addsresponsive.twd.test.ts. All examplemock-sw.jscopies regenerated from the current build (they were at v1.12.1).Known gap
twd-relayannouncestestCountinrun:startfrom all registered tests, so with viewports declared it can announce more than the run executes. That fix belongs in the relay.Testing
viewports.spec.ts,twd-runner-viewport.spec.ts,twdSidebarViewport.spec.tsx,markOtherViewports.spec.ts,twdSidebarResize.spec.tsx, plus additions to the executeTests, bundled, plugin, LogItem and formatLogs specs. 622 tests pass.twdSidebar.spec.tsxnow pinsinnerWidthto 1280: jsdom's default 1024 is below the push threshold.twd-test-appat 1280px and 390px: push vs overlay, the chip, greyed tests in place, the pill during Run All, and the warning on a desktop test run at 390px. No page errors.