Repository navigation
Releases
v1.12.2
TWD's type declarations work again under moduleResolution node16 and nodenext.
Update your service worker
npx twd-js init publicThe worker did not change, but it carries the version number, so a 1.12.1 mock-sw.js logs a version mismatch warning with 1.12.2.
Types under node16 and nodenext
Since 1.7.3, the published .d.ts files used relative imports without file extensions (export { twd } from './twd'). Because the package is "type": "module", TypeScript rejects those imports under node16 and nodenext, so most exports resolved to any: twd, screenDom, userEvent, initTests, TWDSidebar, every twd-js/vite-plugin export and MockedComponent. With skipLibCheck on, nothing reported it. You just lost autocomplete and assertion names like twd.should(el, 'not.a.real.assertion') compiled.
Projects on moduleResolution: "bundler", the default in Vite templates, were not affected.
Now each entry ships as one self-contained declaration file. The twd-js/bundled types moved to dist/bundled.d.mts; the package.json export points at it, so import { initTWD } from 'twd-js/bundled' needs no change.
CI now type-checks the packed package as a consumer under nodenext, node16 and bundler before every release, so this can't regress silently again.
Thanks to @trackoor for the detailed report in #434.
Also in this release
- Dependencies:
preact11.1.0, used by the bundled sidebar. - Docs: a support page with hello@twd.dev, accessibility fixes on the landing, and the AI setup eval now checks the mock service worker.
- Tooling: TypeScript 6.0.3, jsdom 31, vitest, vite, eslint and other dev dependency updates.
Full changelog: v1.12.1...v1.12.2
v1.12.1
removeMockServiceWorker() now removes the mock service worker from your real build output, so it no longer ships to production by accident.
Update your service worker
npx twd-js init publicThe worker did not change, but it carries the version number, so a 1.12.0 mock-sw.js logs a version mismatch warning with 1.12.1.
removeMockServiceWorker() uses the real build output
It used to delete a hardcoded dist/mock-sw.js relative to the working directory. With a custom build.outDir, React Router v7 framework mode (build/client), or a build run from another directory, the worker stayed in production while the plugin logged 🧹 No mock-sw.js found in build, which reads like success.
Now it:
- removes the worker from the output directory of each build,
- skips server builds silently, since Vite only copies
public/into the client output, - warns when a client build has no worker, instead of reporting success.
🧹 twd: removed mock-sw.js from build/clientIf you serve the worker from a custom serviceWorkerUrl, pass the same path:
removeMockServiceWorker({ fileName: 'workers/mock-sw.js' })Nuxt
Nuxt copies public/ outside the Vite build (build.copyPublicDir: false), so the plugin cannot see the file and prints a warning. Remove it in the build script instead:
"build": "nuxt build && rm -f .output/public/mock-sw.js"Also in this release
- Commit or gitignore
mock-sw.js. Getting started now explains both options. Committing it, withremoveMockServiceWorker()in your Vite config, is the recommended one. - Docs: new Where TWD Fits page with the Testing Trophy, a link to the live tour at try.twd.dev, and a page on how the AI skills are tested.
- Dependencies:
@testing-library/user-event14.6.8, plus dev tooling updates (vite, vite-plugin-dts, prettier, lint-staged).
Full changelog: v1.12.0...v1.12.1
v1.12.0
Faster and more deterministic request mocking. On real suites of 300 to 550 tests, run time dropped by about 20% and CI retries went to zero.
Update your service worker
npx twd-js init publicThe speedups need the new mock-sw.js. With an outdated one everything keeps working as before, without the speedup: each mockRequest waits 100ms and the page warns once in the console.
mockRequest no longer sleeps 100ms
Every twd.mockRequest() used to end with a fixed 100ms sleep, a guess at how long the service worker needs to store the rule. It cost 100ms per mock on every machine, and on a slow CPU the guess could be wrong and the request went out unmocked.
Now the service worker confirms each rule, and mockRequest resolves as soon as it is stored: about 1ms, and it keeps waiting while the worker is busy instead of guessing.
waitForRequest resolves when the request happens
It used to check every 100ms, so each call waited ~50ms on average after the request had already happened. Now it resolves on the hit itself, plus two frames for the response to reach the app.
It guarantees the request happened, not that the UI has updated. If your app processes the response asynchronously, wait for the screen with findBy* or twd.waitFor:
await twd.waitForRequest("filtered");
await twd.waitFor(() => expect(screenDom.queryAllByText("old.csv").length).to.equal(0));3000ms defaults, like findBy*
twd.waitForRequest() now waits up to 3000ms by default (was 1000ms), and twd.url().should() up to 3000ms (was 500ms). Both were too short for a slow CI runner. Passing tests are not slower, and explicit retries / retryDelay are respected.
If a test turns flaky after upgrading
The old 100ms sleep gave async work your test did not await time to finish, by luck: a logout() or storage cleanup in beforeEach, a helper at the end of a test. Without it, that work can land in the middle of the next steps. Await it:
beforeEach(async () => {
await logout();
});@typescript-eslint/no-floating-promises on your test files catches it.
Also in this release
- A throwing
afterEachno longer ends the run. It fails that test, which is retried like any failure, and the run continues. A passing test whoseafterEachthrows is no longer reported as passed. - Re-mocking an alias is reliable. A late request for a replaced rule can no longer mark the new rule as executed.
twd.url().should()retries work. An assertion that failed once and passed on a retry used to throw anyway.mock-sw.jsis readable. Built unminified, with a header naming the version and how to regenerate it.- Docs:
findBy*is the default query, with the expected state in the query (findByRole("button", { name: "2", current: "page" }));getRequestCountcan lag one hit behind the UI, so check it insidetwd.waitFor. - Dependencies: dev tooling updates (vitest, jsdom, typescript-eslint, @vitejs/plugin-react, globals).
Full changelog: v1.11.0...v1.12.0
v1.12.0-beta.1
Beta: fixes from running beta.0 on real apps with a slow CI runner. To try it: npm i -D twd-js@beta.
Update your service worker after installing: npx twd-js init public. With an outdated mock-sw.js each mockRequest waits 100ms and the page warns once.
twd.waitForRequest()andtwd.url().should()now wait up to 3000ms by default, likefindBy*(they were 1000ms and 500ms). Passing tests are not slower; explicitretries/retryDelayare respected- An
afterEachthat throws now fails that test (retried like any failure) instead of ending the whole run. A passing test whoseafterEachthrows is no longer reported as passed - Correcting the beta.0 notes:
waitForRequestguarantees the request happened, not that the UI has updated. Wait for the UI withfindBy*ortwd.waitFor, and put the expected state in the query (findByRole("button", { name: "2", current: "page" })) getRequestCountcan lag one hit behind the UI: check it insidetwd.waitFor
If a test turns flaky with this beta, look for un-awaited async code in beforeEach or at the end of a test (a logout(), storage cleanup). The old 100ms sleep in mockRequest gave it time to finish by luck. Await it; @typescript-eslint/no-floating-promises on your test files catches it.
See #402 for full context.
Full Changelog: v1.12.0-beta.0...v1.12.0-beta.1
v1.12.0-beta.0
Beta: faster and more deterministic request mocking. To try it: npm i -D twd-js@beta.
Update your service worker after installing: npx twd-js init public. The speedups need the new mock-sw.js. With an outdated one everything keeps working as before, without the speedup, and the page warns once.
mockRequestno longer sleeps 100ms per call: it resolves as soon as the service worker confirms the rule is stored, and keeps waiting for it while it is busy instead of guessingwaitForRequestresolves when the request happens instead of on the next 100ms polling tick, then waits two frames so the mocked response has rendered- Re-mocking an alias is reliable: a request for a replaced rule can no longer mark the new rule as executed
twd.url().should()now passes when a retry passes (it used to throw the first failure)mock-sw.jsis built unminified, with a header naming the version and how to regenerate it
If a test turns flaky with this beta, look for un-awaited async code in beforeEach or at the end of a test (a logout(), storage cleanup). The old 100ms sleep in mockRequest gave it time to finish by luck. Await it; @typescript-eslint/no-floating-promises on your test files catches it.
See #398, #399, #400 and #401 for full context.
Full Changelog: v1.11.0...v1.12.0-beta.0
v1.11.0
A maintenance release: a clearer Node support policy, Preact 11 in the bundled sidebar, and docs for the new twd-lint package.
Node 20 is now the minimum, and it is actually tested
engines.node moves from >=16 to >=20.
The only parts of twd-js that run in Node are the CLI (npx twd-js init) and the Vite plugin. Everything else runs in the browser. CI now packs the tarball, installs it into an empty project on Node 20, and runs both. The claim in engines is checked on every pull request instead of being a guess.
The test suite runs on Node 22, 24 and 26, because the Vitest and jsdom toolchain needs Node 22 or newer. That is a requirement of the repo's dev tooling, not of your app.
Older Node versions will probably still work, they are just no longer tested. npm and pnpm only warn when engines does not match. Yarn 1 users on Node below 20 need --ignore-engines.
Preact 11 in the bundled sidebar
twd-js/bundled ships Preact, which renders the sidebar for Vue, Angular, Solid and other non-React setups. It moves from Preact 10 to Preact 11. There is no API change, and the sidebar was checked by hand with the theme, search and pace controls enabled.
Also in this release
- Dependencies: chai 6.3.0 and @testing-library/dom 10.4.2.
- Docs: a new Linting page for twd-lint, which catches a missing
await, a wrong runner import or a forgottenit.onlybefore a browser run. The AI agents section now leads with the headless twd-cli loop, with twd-relay as an opt-in. - README: refreshed to match twd.dev, with an agent-neutral AI quick start and the full ecosystem table, so the npm page reflects where TWD is today.
Full changelog: v1.10.1...v1.11.0
v1.10.1
A fix for in-browser test runs that failed only in CI, and the first release published with npm Trusted Publishing.
Tests that passed locally and failed in the pipeline
The twd() Vite plugin creates an import edge Vite cannot follow, and never declared it. The dependency scanner walks real files, so it does not enter the virtual module that imports twd-js/bundled, and the test files behind that module's import.meta.glob, which import twd-js and twd-js/runner, are invisible for the same reason.
Vite therefore discovered all three while the browser was already loading the page, and full-reloaded once per discovery. In a dev session that is a flicker nobody notices. Under a headless runner the page reloads out from under the run, and it fails on:
Waiting for selector #twd-sidebar-root
which blames the sidebar for something the sidebar did not do.
An empty node_modules/.vite is the trigger, so it landed on every CI run and on no warm dev machine. It passed locally and failed the moment it reached a pipeline, which is also the moment the message was least useful.
The plugin now declares those three entries in its config() hook, which pre-bundles them at server start, before the first request. Vite merges the hook's return into your own config, so an existing optimizeDeps.include survives. There is nothing to change in your setup.
Publishing now takes two steps
This is the first release authenticated with npm Trusted Publishing: a short-lived GitHub OIDC token rather than a long-lived NPM_TOKEN, which is one fewer credential to hold, rotate and leak.
The workflow runs npm stage publish, which uploads the tarball and defers proof-of-presence. A green CI run means the version is staged, not live. It goes live on approval in npm's UI, or with npm stage approve. That deferral is the point: the credential CI holds can stage a release but cannot complete one on its own.
Nothing changes for anyone installing the package.
Also in this release
- Docs: the mocking examples now follow our own selector guidance instead of contradicting it.
- Docs: a Recording page covering
twd-cli1.7.0/1.8.0 and the record action. - 8 dependabot bumps.
Full changelog: v1.10.0...v1.10.1
v1.10.0
Layout snapshots, in your browser, with no SaaS account and no containers.
twd.matchLayout(el, name) captures a DOM node to an anchored grid of bits and compares it against a committed .snap reference, throwing when the geometry moved. The reference is a text file you commit, with an ASCII preview inside it, so a layout change is reviewable in a pull request without opening an image.
const landing = await screenDom.findByTestId('landing');
await twd.matchLayout(landing, 'landing');There is no expect to write. It throws, the same way twd.should does.
It watches geometry, not appearance
It sees a block that grows, shrinks or moves, a list that appears, a container that wraps, a flex or grid that collapses. It does not see a changed string, a subtly shifted colour, or white text on white. That is deliberate: content is already covered by twd.should, and the two are meant to be used together. It is called matchLayout and not matchSnapshot for the same reason, because with matchSnapshot people expect Percy and then report a changed string as a bug.
Layout snapshots ship as a beta feature. They are strictly additive: without
matchLayoutin a test, nothing changes. What may still change is the.snapformat and the API.
The verdict comes from twd-cli, not the sidebar
In the browser sidebar, layout snapshots are skipped. The sidebar resizes the page, and a developer's viewport is whatever their window happens to be, so a reference created there would fail for everyone else. twdSnapshot({ debug: true }) opts in locally for inspection, and twd-cli 1.6.0 or newer is what actually decides a snapshot.
A reference records the viewport it was taken at, and a mismatch skips rather than fails. That is what keeps the feature from being flaky: a resized window never produces a red test you did not cause.
Removed: twd.viewport()
twd.viewport() and twd.resetViewport() are gone.
The command shipped in 1.6.0 as a beta and did not survive contact with real users. It simulated a viewport by constraining the body, overriding innerWidth, innerHeight and matchMedia, and rewriting CSS @media rules by hand at runtime, and that machinery did not hold up in practice. Anyone calling either method has to drop those calls.
This is not a major release because usage of the command is effectively nil, and we would rather start the responsive story from a clean slate than keep a method that makes people think the problem is already solved.
Also in this release
- Failure diagnostics. A failing test now reports the route it was on and which mock rules never fired, as plain data the reporter renders.
- A sidebar execution speed selector, and the fix behind it: pacing state lived in module scope but the module ships in more than one bundle, so a pace set from the sidebar never reached the copy the runner reads.
- A fix without which the Vite plugin did not load at all.
rollupOptions.externallisted only the unprefixedfsandpath, so rolldown bundled thenode:prefixed imports and emitted broken interop. - 14 dependency updates.
Full guide: Layout Snapshots.
What's Changed
- chore(deps-dev): bump @vitejs/plugin-react from 6.0.3 to 6.0.5 by @dependabot[bot] in #317
- chore(deps-dev): bump lint-staged from 17.1.0 to 17.2.0 by @dependabot[bot] in #318
- chore(deps-dev): bump globals from 17.7.0 to 17.8.0 by @dependabot[bot] in #319
- chore(deps-dev): bump undici from 7.28.0 to 7.29.0 by @dependabot[bot] in #320
- chore(deps): bump preact from 10.29.7 to 10.29.8 by @dependabot[bot] in #321
- chore(deps-dev): bump vite from 8.1.3 to 8.2.1 by @dependabot[bot] in #324
- chore(deps-dev): bump globals from 17.8.0 to 17.11.0 by @dependabot[bot] in #325
- chore(deps-dev): bump eslint from 10.7.0 to 10.8.1 by @dependabot[bot] in #326
- docs: component testing in the real browser, and fix the .tsx silent-skip trap by @kevinccbsg in #328
- docs: replace the blank test route with a component host helper by @kevinccbsg in #329
- chore(deps): bump @testing-library/user-event from 14.6.1 to 14.6.6 by @dependabot[bot] in #330
- chore(deps-dev): bump conventional-changelog from 8.1.0 to 8.1.3 by @dependabot[bot] in #331
- chore(deps-dev): bump @types/react-dom from 19.2.3 to 19.2.5 by @dependabot[bot] in #332
- docs: document twd-cli sharding and the missing CI config options by @kevinccbsg in #334
- feat: failure diagnostics — report the route and mock-rule state on failure by @kevinccbsg in #335
- chore(deps-dev): bump vitepress from 2.0.0-alpha.17 to 2.0.0-alpha.19 by @dependabot[bot] in #322
- chore(deps-dev): bump typescript-eslint from 8.62.1 to 8.68.0 by @dependabot[bot] in #333
- chore(deps-dev): bump browserslist from 4.28.4 to 4.28.9 by @dependabot[bot] in #336
- feat: matchLayout, in-browser layout snapshots (beta) by @kevinccbsg in #337
- feat: remove the viewport command by @kevinccbsg in #338
- fix(matchLayout): load the snapshot plugin, and say where the layout moved by @kevinccbsg in #339
- feat(sidebar): add an execution speed selector by @kevinccbsg in #340
- chore(release): 1.10.0 by @kevinccbsg in #341
Full Changelog: v1.9.0...v1.10.0
v1.9.0
Command pacing for recorded runs. twd-cli --record can now ask twd-js to space out its own command loop, so the video is watchable at full frame rate rather than a one second blur, with typing rendered character by character instead of appearing all at once.
Pacing is a tooling hook (window.__twdSetPace), not public API. It is not exported from the package and is not on the twd object, so it cannot be left behind in a spec file and quietly slow CI. With pacing off a run allocates no promise and schedules no timer.
Needs twd-cli 1.4.0 or newer to drive it. Otherwise a maintenance release: file upload example, landing hero video, SEO and docs work, and dependency updates.
What's Changed
- chore(deps-dev): bump @vitejs/plugin-react from 6.0.2 to 6.0.3 by @dependabot[bot] in #292
- chore(deps-dev): bump vite from 8.0.16 to 8.1.3 by @dependabot[bot] in #293
- chore(deps-dev): bump typescript-eslint from 8.61.0 to 8.62.1 by @dependabot[bot] in #290
- chore(deps-dev): bump vitest from 4.1.9 to 4.1.10 by @dependabot[bot] in #294
- chore(deps-dev): bump @vitest/eslint-plugin from 1.6.20 to 1.6.23 by @dependabot[bot] in #295
- chore(deps-dev): bump vite-plugin-dts from 5.0.2 to 5.0.3 by @dependabot[bot] in #296
- chore(deps-dev): bump prettier from 3.8.4 to 3.9.5 by @dependabot[bot] in #297
- feat(docs): landing hero video (twd.dev + twd-js page) by @kevinccbsg in #298
- chore(deps-dev): bump eslint from 10.6.0 to 10.7.0 by @dependabot[bot] in #300
- chore(deps-dev): bump lint-staged from 17.0.8 to 17.1.0 by @dependabot[bot] in #301
- chore(deps-dev): bump conventional-changelog from 8.0.0 to 8.1.0 by @dependabot[bot] in #303
- chore(deps-dev): bump brace-expansion from 5.0.6 to 5.0.7 by @dependabot[bot] in #304
- Feat/file upload example by @RLinV1 in #299
- docs: add RLinV1 as a contributor for doc by @allcontributors[bot] in #306
- docs: CDN installation for Vanilla JS and HTMX by @kevinccbsg in #307
- docs(seo): broaden framework support messaging + structured data by @kevinccbsg in #308
- docs: add auto-generated llms-full.txt by @kevinccbsg in #309
- docs: AI agent-loop video on landing + AI docs, media optimization by @kevinccbsg in #310
- chore(deps): bump preact from 10.29.3 to 10.29.7 by @dependabot[bot] in #312
- chore(deps-dev): bump @testing-library/jest-dom from 6.9.1 to 7.0.0 by @dependabot[bot] in #311
- chore(deps-dev): bump prettier from 3.9.5 to 3.9.6 by @dependabot[bot] in #313
- chore(deps): bump postcss from 8.5.15 to 8.5.23 in /examples/vue-twd-example by @dependabot[bot] in #314
- chore(deps-dev): bump postcss from 8.5.16 to 8.5.23 by @dependabot[bot] in #315
- feat(pace): command pacing for recorded runs by @kevinccbsg in #316
New Contributors
Full Changelog: v1.8.2...v1.9.0
v1.8.2
Accessibility fix for the sidebar (improved describe-block contrast and legibility). Otherwise a maintenance release: dependency updates, npm metadata cleanup, and docs.
What's Changed
- chore(deps-dev): bump @types/react from 19.2.14 to 19.2.17 by @dependabot[bot] in #266
- chore(deps-dev): bump typescript-eslint from 8.60.0 to 8.60.1 by @dependabot[bot] in #265
- chore(deps-dev): bump vitest from 4.1.7 to 4.1.8 by @dependabot[bot] in #264
- chore(deps-dev): bump lint-staged from 17.0.5 to 17.0.7 by @dependabot[bot] in #263
- fix(a11y): address audit findings on docs site + sidebar by @kevinccbsg in #267
- chore(deps-dev): bump shell-quote from 1.8.3 to 1.8.4 in /examples/tutorial-example by @dependabot[bot] in #268
- chore(deps-dev): bump @vitest/eslint-plugin from 1.6.17 to 1.6.20 by @dependabot[bot] in #269
- chore(deps-dev): bump prettier from 3.8.3 to 3.8.4 by @dependabot[bot] in #270
- chore(deps-dev): bump vite-plugin-dts from 5.0.0 to 5.0.2 by @dependabot[bot] in #271
- chore(deps-dev): bump typescript-eslint from 8.60.1 to 8.61.0 by @dependabot[bot] in #272
- chore(deps-dev): bump vite from 8.0.10 to 8.0.16 in /examples/vue-twd-example by @dependabot[bot] in #273
- chore(deps-dev): bump vite from 8.0.10 to 8.0.16 in /examples/twd-test-app by @dependabot[bot] in #274
- chore(deps-dev): bump vite from 8.0.10 to 8.0.16 in /examples/tutorial-example by @dependabot[bot] in #275
- chore(deps): bump react-router from 7.15.0 to 7.15.1 in /examples/twd-test-app by @dependabot[bot] in #276
- chore(deps): bump form-data from 4.0.5 to 4.0.6 in /examples/twd-test-app by @dependabot[bot] in #277
- chore(deps-dev): bump undici from 7.25.0 to 7.28.0 by @dependabot[bot] in #278
- docs: add accessibility statement page by @kevinccbsg in #279
- chore(deps-dev): bump @vitest/coverage-v8 from 4.1.8 to 4.1.9 by @dependabot[bot] in #280
- chore(deps-dev): bump eslint from 10.4.1 to 10.5.0 by @dependabot[bot] in #281
- chore(deps-dev): bump lint-staged from 17.0.7 to 17.0.8 by @dependabot[bot] in #283
- chore(deps-dev): bump eslint from 10.5.0 to 10.6.0 by @dependabot[bot] in #284
- chore(deps): bump preact from 10.29.2 to 10.29.3 by @dependabot[bot] in #285
- chore(deps-dev): bump globals from 17.6.0 to 17.7.0 by @dependabot[bot] in #287
- chore(deps-dev): bump conventional-changelog from 7.2.0 to 8.0.0 by @dependabot[bot] in #286
- docs(ci): experimental cross-browser testing (twd-runner) section by @kevinccbsg in #288
- chore(deps): bump uuid and istanbul-lib-processinfo in /examples/tutorial-example by @dependabot[bot] in #289
Full Changelog: v1.8.1...v1.8.2