8000 test: run the tests in real browsers with vitest browser mode by morellodev · Pull Request #326 · awesome-reveal/awesome-reveal · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
3a7523c
test: add shared browser helpers and a reduced motion command
morellodev Oct 18, 2026
3aacdb9
test: strengthen the checks of the browser test helpers
morellodev Oct 18, 2026
12517e4
test: test the pure core logic in node
morellodev Oct 18, 2026
8c6b5ef
test: keep the core bundle size of the pure logic tests
morellodev Oct 18, 2026
6aa65a5
test: move the core dom tests to browser mode
morellodev Oct 18, 2026
48d76ac
test: tighten the core browser tests
morellodev Oct 18, 2026
68c8316
test: run the contract and the react tests in browser mode
morellodev Oct 18, 2026
f058a7e
test: share the browser test helpers of the contract
morellodev Oct 18, 2026
3aed33a
test: run the vue tests in browser mode
morellodev Oct 18, 2026
05c0eb3
test: tighten the vue browser tests
morellodev Oct 18, 2026
0be7d89
test: run the astro tests in browser mode, and rename the e2e project
morellodev Oct 18, 2026
e2e33c6
build: remove jsdom and the test fakes
morellodev Oct 18, 2026
09b1172
ci: run the browser tests with the older framework versions
morellodev Oct 18, 2026
1e050ed
build: run the related browser tests in the pre-commit hook
morellodev Oct 18, 2026
7a73e6c
docs: describe the browser mode tests
morellodev Oct 18, 2026
aec9622
docs: fix the reduced motion advice and shorten the test rules
morellodev Oct 18, 2026
6d57f83
test: close the gaps that the final review found
morellodev Oct 18, 2026
d282dcb
ci: upload the browser test results of the framework job
morellodev Oct 18, 2026
8fb92b3
docs: clarify the repeats advice in the browser test rule
morellodev Oct 18, 2026
c683ab5
build: run the react and vue browser projects in full in the pre-comm…
morellodev Oct 18, 2026
1e1cebc
build: run the framework browser projects only for source changes of …
morellodev Oct 18, 2026
878756d
build: remove the tests from the pre-commit hook
morellodev Oct 18, 2026
7b93811
test: reset reduced motion to no-preference, not to the system setting
morellodev Oct 18, 2026
63bf127
build: run the browser tests in the watch script
morellodev Oct 18, 2026
5725678
build: dedupe the lockfile
morellodev Oct 18, 2026
109ad27
test: run the Astro e2e tests of each browser in a separate file
morellodev Oct 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/rules/astro/adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,5 +18,5 @@ paths:
- The Vite config of Astro aliases the bare `astro` import to its types. In that environment, import the Astro API, such as `build`, by its resolved path, as `test/build-site.ts` does.
- The programmatic `build` and `preview` need `root` and `outDir` as filesystem paths. With file URL strings, Astro builds 0 pages. The preview server of `@astrojs/node` reports the configured port, so port 0 does not work.
- Astro 6 and 7 give different output: Astro 6 adds `data-astro-source-file` and whitespace in the container, and the minifiers write `@media(` or `@media (` and other quotes. Keep the test patterns tolerant.
- The example and `astro:browser` need Astro 7, because `@astrojs/node` 11.1.3 and later need Astro 7.2.1 or later. The Astro 6 CI job runs only `astro:unit` and `astro:ssr`.
- The example and `astro:e2e` need Astro 7, because `@astrojs/node` 11.1.3 and later need Astro 7.2.1 or later. The Astro 6 CI job runs `astro:unit`, `astro:ssr` and `astro:browser`.
- `tsc` cannot read `.astro` files. `test/astro.d.ts` declares them for the tests. `astro check` reports only the files of the tsconfig `include`, so the example tsconfig includes `packages/astro/src/**/*.astro`. The `tsconfig.base.json` paths resolve the imports to the sources. The e2e test also builds the example on the sources.
4 changes: 2 additions & 2 deletions .claude/rules/ci/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ paths:
- Check out with `persist-credentials: false`.
- Run `actionlint` after each change.
- The `lint` job runs `astro check` in the Astro example, because `tsc` cannot read `.astro` files.
- The `test` job uses the catalog version of each framework. The `framework` job tests the older majors in the peer ranges, with only the unit and SSR projects. The core browser tests do not use a framework, and the Astro example needs the current Astro major.
- The `test` job uses the catalog version of each framework. The `framework` job tests the older majors in the peer ranges. It runs the unit, SSR and browser projects of its package in Chromium only, in the Playwright container. It sets `shell: bash`, because its steps split the matrix values with `read -r -a`. The Astro example needs the current Astro major.
- Run the browser tests in the `mcr.microsoft.com/playwright` container, with `--user 1001` as the Playwright CI guide shows. The image has the browsers and their system packages. A `playwright install --with-deps` step takes about 70 s on `ubuntu-latest`, and the image pull takes about 30 s.
- Keep the image tag equal to the `playwright` version in `pnpm-lock.yaml`. If the versions differ, the tests fail with "Executable doesn't exist". Update the tag in the PR that upgrades Playwright.
- In the container, `run` steps use `sh`, not `bash`, and `jq` is not available.
- In the container, `run` steps use `sh` unless the job sets `shell: bash`. `jq` is not available.
- Do not cache the Playwright browsers. The Playwright docs say that a cache restore takes about as long as the download.
- `actions/upload-artifact` skips hidden files by default. An upload of `.vitest/` needs `include-hidden-files: true`.
- The `smoke` job runs `scripts/smoke.mjs`. It packs the packages, installs the tarballs into a clean project outside the workspace, and builds, type-checks and server-renders it. Most cases also serve the build and check in Chromium that `reveal.css` hides an element below the fold until it reveals. A pnpm override makes the adapters use the core tarball and not the registry. Its matrix covers the exact minimum and the newest framework version of each peer range. All cases except `core` and `compat` have a browser check. For them, the job installs Chromium on the runner, outside the Playwright container, for about 70 s more. Change a peer range and this matrix together.
Expand Down
4 changes: 2 additions & 2 deletions .claude/rules/react/adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ paths:
- Support React 18 and 19. CI runs the tests with each version. Keep `forwardRef` until the peer range drops React 18.
- `useReveal` reads `revealed` from `createReveal` with `useSyncExternalStore`, and renders `data-awesome-reveal` from it. `useCascade` uses the same binding with `createCascade`. Neither hook calls `reveal()`, because that breaks hydration. Core removes `data-awesome-reveal` and starts `play` in the task of the report. React renders the same removal later, from `revealed`. Do not start the animation in a passive effect.
- Keep `"use client"` at the top of each module that uses hooks. The build keeps one directive for each module.
- `react:unit` runs in jsdom, with the IntersectionObserver and `Element.animate` mocks of `@awesome-reveal/test-utils`. Use `intersect()` from `test/intersect.ts` to change the visibility, because it wraps the change in `act`. The core browser tests cover the real browser behavior.
- `react:browser` runs the component and hook tests in real browsers with `vitest-browser-react`. Do not wrap the tests in `act`.
- React reports `act()` warnings and server render warnings only through the console, so the shared console setup catches them.
- Type tests in `test/types` run with `react:unit`.
- The ref callback and the layout effect both give the element to core through `sync`. The ref callback queues it in a microtask, so it runs after the layout effect applies `setOptions` of the same commit. Without the wait, core starts the animation with the options of the previous render. The microtask is also necessary for a commit that renders only a child: a child can mount the element, or Suspense can hide and show it, and the layout effect of the hook does not run. React also detaches and attaches the same element in one commit when a callback ref changes, as an inline callback does on each render. The microtask sees only the final element, so the entrance does not replay.
- The first client render equals the server render: the server snapshot of the store is `revealed` too, so it is hidden, also when `when` is `true`. `test/hydration.test.tsx` renders a literal server markup, hydrates it in jsdom and fails on a mismatch warning. Keep one hydration test for each way to render the element.
- The first client render equals the server render: the server snapshot of the store is `revealed` too, so it is hidden, also when `when` is `true`. `test/browser/hydration.test.tsx` renders a literal server markup, hydrates it in a browser and fails on a mismatch warning. Keep one hydration test for each way to render the element.
- `getProps` merges only the `ref` and sets `data-awesome-reveal`. It passes `style` through, because the package `reveal.css` hides the element, so a `style` before or after the spread is safe. `data-awesome-reveal` and `data-awesome-reveal-attached` are reserved.
- The detach in `ref(null)` needs React to call a callback ref with `null`. React 19 documents that a future version removes this call for a callback with no cleanup. React 18 logs an error when a callback returns a function. Check the detach when a React version drops the call.
10 changes: 10 additions & 0 deletions .claude/rules/testing/browser-tests.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
paths:
- "packages/*/test/browser/**"
- "packages/test-utils/src/{layout,spies,reduced-motion,commands,contract}.ts"
---

# Browser tests
Expand All @@ -10,3 +11,12 @@ paths:
- Use a long `duration` (60 s) when a test inspects a running animation, so that it does not finish first.
- Wait for a DOM change with `expect.element(...)`. Use `settle()` when you expect no change.
- In CI, a failed test runs again, and the first retry records a Playwright trace. Vitest copies the traces and the failure screenshots into `.vitest/attachments`, and CI uploads that folder.
- Change the reduced motion setting with `setReducedMotion()`. It sends the `emulateReducedMotion` command to `ctx.page`, which changes the media of the whole page, not only of the test frame. The browser setup file resets it to `"no-preference"` after each test. Do not reset it with `null`: then WebKit in the CI container uses its system setting, which is `reduce`. The media query event arrives only after a rendering update, so `setReducedMotion()` waits with `settle()`. Do not add another wait.
- `emulateMedia({ media: "print" })` sends no `beforeprint` or `afterprint` event. A print test dispatches both events itself.
- Fault injection uses `vi.stubGlobal`, an invalid input, `withoutAnimate()` or `rejectEasing()`. All other spies call the real API.
- `interceptObserver()` is a pass-through spy on the `IntersectionObserver` constructor. It lets a test call the real callback with entries that it builds. Use it only when the real layout cannot make the entry:
- a cross-origin frame with no `rootBounds`
- several entries in one report
- a threshold that no layout reaches
- Compare elements, observers and animations by identity: use `expectSame()`, or `toHaveLength()` and then `toBe()`. `toEqual` treats two `IntersectionObserver` or two `Animation` instances as equal, and it compares DOM nodes with `isEqualNode`.
- Core reports each message one time per module, so a `--repeats` run sees a report only one time. In a `--repeats` run, use `-t` to leave out the report tests that check a message from the browser. You cannot add a counter to these messages.
12 changes: 5 additions & 7 deletions .claude/rules/testing/test-utils.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,9 @@ paths:

- `@awesome-reveal/test-utils` is private. It has no build, and release-please does not know it.
- The adapters do not list it as a dependency. They resolve it through the `tsconfig.base.json` paths and the `testUtils` alias in `vitest.config.ts`. A `workspace:*` dev dependency makes `pnpm publish` fail, because test-utils has no `version` field.
- Keep it free of frameworks. Each adapter wraps `intersect()` in its own update scope, such as React `act` or an awaited Vue `nextTick`.
- Each adapter imports the setup files from its own `test/setup` files. Then `tsc -p packages/<package>/test` sees the jest-dom matcher types.
- The console setup fails a test on each `console.error` or `console.warn` call, because frameworks report warnings, such as invalid props, only through the console.
- The DOM setup adds the React copy of `reveal.css` to the document with `installStylesheet()`, because Vitest turns CSS imports into empty strings. The `test/stylesheet.test.ts` of each other adapter checks that its copy equals the React copy. jsdom does not update the computed style of an element that is not in the document. Attach the element to `document.body` before you check `toHaveStyle` after a change.
- `contract.ts` (`describeContract`, `describeCascadeContract`) and `contract-ssr.ts` (`describeSSRContract`) hold one scenario list that every adapter runs, so that all adapters behave the same. Each adapter has a `test/contract.test.ts(x)`, and the SSR contract runs from the `ssr.test` file of the adapter. The Astro contract runs in jsdom, and its harness builds the markup of `Host.astro` by hand, so `ssr.test.ts` checks the real output.
- Keep it free of frameworks, so that all adapters share the same helpers. Each adapter binds its framework in its own harness.
- The console setup fails a test on each `console.error` or `console.warn` call, because frameworks report warnings, such as invalid props, only through the console. It accepts the Vitest relay of a window error that `collectWindowErrors()` collected. Vitest relays the error to `console.error` before any listener of the test runs, also in the capture phase in Chromium.
- `contract.ts` (`describeContract`, `describeCascadeContract`) and `contract-ssr.ts` (`describeSSRContract`) hold one scenario list that every adapter runs, so that all adapters behave the same. Each adapter has a `test/browser/contract.test.ts(x)`, and the SSR contract runs from the `ssr.test` file of the adapter. The contract mounts into `createStage()`, below the fold, and scrolls with `scrollIntoView()`, `showPart()` and `scrollToTop()`. The Astro harness builds the markup of `Host.astro` by hand, so `ssr.test.ts` checks the real output. A Vue harness unmounts with `cleanup()`, not with `screen.unmount()`.
- Do not skip a contract scenario to make a run pass. A scenario that fails is a bug of the adapter.
- Scenarios that expect a report must collect it: reports are thrown from a microtask, which Vitest counts as an unhandled error. Use a unique error message in each scenario and for each harness, so that a once-per-page report of an identical message cannot hide it. Core tests use `collectReports()` from `@awesome-reveal/test-utils/reports`. The contract wraps `queueMicrotask` instead, because React schedules its own work with it.
- Server markup in a hydration test is a literal. React 18 warns when jsdom, which has a `document`, renders it with `renderToString`.
- Scenarios that expect a report must collect it: reports are thrown from a microtask, which Vitest counts as an unhandled error. Use a unique error message in each scenario and for each harness, so that a report of an identical message cannot hide it: core reports each message one time per module. Each test that expects a report uses `collectReports()` from `@awesome-reveal/test-utils/reports`. Read it with `expect(await reports())`. It wraps `queueMicrotask` and does not hold the microtasks, because React schedules its own work with it.
- Server markup in a hydration test is a literal. `useReveal` uses `useLayoutEffect` where `document` exists, and then React 18 warns in `renderToString`.
2 changes: 1 addition & 1 deletion .claude/rules/vue/adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,5 @@ paths:
- `defineReveal` runs `setOptions` in a post-flush watcher, after the patch. A pre-flush watcher runs while the old element is still attached. So an `as` change and a `when` change in the same tick play the entrance on the old element. Core removes `data-awesome-reveal` and plays in the task of the report. Vue renders the same removal later, from `revealed`.
- `v-reveal` and `v-cascade` create one store for each element, with `createReveal` or `createCascade`, and set `data-awesome-reveal` itself, so the reveal belongs to its element. A directive keeps no state across elements, so a new element, such as a changed `key` or tag, starts a new reveal. The directive is `deep`, so that a reactive options object that changes in place calls `updated`. Its `updated` hook calls `setOptions`. A patch of a `style` binding cannot show a hidden element, because the package `reveal.css` hides it.
- `getSSRProps` of the directives returns only `hiddenAttributes` or `cascadeHiddenAttributes`. Do not add a style there: of all directives, the hydration check of Vue knows only `v-show`, so a style that only the server renders causes a mismatch warning.
- Mount with `attachTo: document.body` when a test checks `toHaveStyle` after a change. The test setup adds `reveal.css`, so `toHaveStyle({ opacity: "0" })` checks the hidden state. `test/setup/dom.ts` unmounts the wrappers after each test.
- The tests render with `vitest-browser-vue` into the page, which loads the Vue copy of `reveal.css` through `#reveal-style.css`. Unmount with `cleanup()`, not with `screen.unmount()`.
- `describeDocs` does not check the `vue` fences.
Loading
Loading
0