Skip to content

feat: responsive testing with named viewports and an overlay sidebar - #445

Merged
kevinccbsg merged 9 commits into
mainfrom
feat/responsive-testing
Nov 19, 2026
Merged

kevinccbsg merged 9 commits into
mainfrom
feat/responsive-testing

Conversation

@kevinccbsg

@kevinccbsg kevinccbsg commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

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.

// vite.config.ts (same options on initTWD; defineViewports() from twd-js/runner for the React setup)
twd({
  viewports: {
    mobile: { maxWidth: 767 },
    desktop: { minWidth: 1024 },
  },
  defaultViewport: 'desktop', // optional: untagged tests count as desktop
});

describe('Header', { viewport: 'mobile' }, () => { ... });
it('shows summary as cards', { viewport: ['mobile', 'tablet'] }, async () => { ... });

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 / .skip accept options as the second argument. The two-argument form is unchanged.
  • A test inherits its describe viewport; a test-level value replaces it. Untagged tests run everywhere unless defaultViewport is set.
  • Matching uses window.matchMedia (falls back to innerWidth without it), the same rule the app's CSS follows.
  • The run set is fixed at run start. .only applies inside the matching set, so an out-of-viewport .only does not suppress the rest. The play button always runs.
  • Unknown viewport names warn once and never match. Invalid definitions throw at startup.
  • New window events: twd:run-start { total }, twd:test-end { status }, twd:run-end (always fired).
  • executeTests({ viewport }) in runner-ci, ready for twd-cli.

Sidebar

  • Live viewport chip (mobile · 390px). The Run All label stays as it is.
  • Non-matching tests stay in place in their describe, greyed with a badge naming their viewport. A describe whose 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.
  • Resizing re-renders only the chip until the width crosses a breakpoint.

Lighter header

  • Breaking (visible): the mock rules button (Rules: 0/0 triggered) is now hidden by default. A new mockRules option on initTWD, the twd() plugin and TWDSidebar brings it back, following search and pace.
  • The version moved from the run-buttons row to the chip row, so the buttons fit on one line on narrow sidebars.
  • Playing an out-of-viewport test prepends a warning log: Written for desktop (min 1024px). Ran at 390px, so layout differences are expected.
  • Overlay mode when less than 768px of room is left for the app: no <html> margin, width min(sidebar width, 100vw - 56px) so the app always peeks out.
  • In overlay mode a run hides the sidebar behind a progress pill (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.
  • Two new theme tokens: viewportOtherText, viewportBadgeBg.

Also

  • Vite plugin types gain viewports / defaultViewport.
  • Docs: new Responsive Testing page (sidebar, llms.txt, llms-full order) and theming tokens.
  • Design spec: specs/2026-11-19-responsive-testing-design.md.
  • examples/twd-test-app declares viewports and adds responsive.twd.test.ts. All example mock-sw.js copies regenerated from the current build (they were at v1.12.1).

Known gap

twd-relay announces testCount in run:start from all registered tests, so with viewports declared it can announce more than the run executes. That fix belongs in the relay.

Testing

  • Tests written first (TDD): new 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.tsx now pins innerWidth to 1280: jsdom's default 1024 is below the push threshold.
  • Lint has no errors, and the consumer type checks pass under nodenext, node16 and bundler.
  • Checked in headless Chrome against twd-test-app at 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.

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.
@kevinccbsg
kevinccbsg merged commit 17bdaac into main Nov 19, 2026
10 checks passed
@kevinccbsg
kevinccbsg deleted the feat/responsive-testing branch November 19, 2026 22:57
@kevinccbsg kevinccbsg mentioned this pull request Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant