Portable UI testing utilities that unify test code across frameworks and libraries. The project provides a collection of packages for describing UI scenes and interacting with components consistently whether you test with React, Playwright or other tooling.

Documentation is available at https://atomic-testing.dev/.

This repository contains multiple packages under the packages/ directory, including but not limited to:

• @atomic-testing/core – core APIs for defining scene parts and running tests.

• @atomic-testing/react-legacy, @atomic-testing/react-18, and @atomic-testing/react-19 – adapters for React applications.

• @atomic-testing/playwright – integration with Playwright for end-to-end tests.

• Component driver packages such as @atomic-testing/component-driver-html and Material UI variants, used to drive specific UI components.

  runner.

The stable public API is the . barrel exports of the in-scope packages — core, dom-core, react-core, react-18, react-19, react-legacy, vue-3, playwright, and component-driver-html. That surface is frozen under SemVer, machine-checked by a committed API Extractor report per package (etc/<package>.api.md), and governed by a documented deprecation lifecycle. Anything else — every @atomic-testing/internal-* package and every export tagged @internal — is not covered by the guarantee. Full policy, including the framework/Playwright/Node support matrix: ADR-006.

Material UI moves fast and each major has a distinct rendered DOM, so this project ships one driver package per MUI major (see ADR-003). To keep the maintained surface focused, older majors reach end of support once newer ones are stable.

MUI 5 / MUI-X 5 are no longer supported as of 2026-06-27. The @atomic-testing/component-driver-mui-v5 and @atomic-testing/component-driver-mui-x-v5 packages remain installable at 0.81.0 but receive no fixes, new drivers, or CI/e2e coverage. Their source and full history have been extracted to atomic-testing/component-driver-mui-v5. New work targets v6/v7/v9 (MUI-X also v8 and v9). Rationale and migration notes: ADR-005.

Note: MUI Core has no v8 — it jumped 7.3.11 → 9.0.0 to unify versioning with MUI X, so @atomic-testing/component-driver-mui-v9 is the successor to v7 (there is no -mui-v8 package).

Note: the MUI-X date/time picker drivers originally shipped only in the v5 package. The v9 package revives a read-capable DesktopDatePicker driver (rewritten for the v9 PickersSectionList field DOM); writing a value and the other picker variants are tracked as follow-ups.

The fastest way in is the scaffolder. Run it inside your existing project — it detects your framework, runner, package manager, and design system, then writes a runner config, an example component with its ScenePart, and a passing test:

npm create atomic-testing@latest
# or
pnpm create atomic-testing
# or
yarn create atomic-testing

Full guides, the support matrix, and examples are in the documentation.

Prefer to install manually? Add the packages you need — a minimal React setup:

pnpm add @atomic-testing/core @atomic-testing/react-19 @atomic-testing/component-driver-html

Then define your scene parts and create a test engine for your framework; the manual installation guide in the docs has the full walkthrough.

Design rationale for major decisions — the component-driver pattern, versioning policy, locator boundaries — is recorded as ADRs (architecture decision records). See the ADR table in agent-docs/INDEX.md for the full list.

See ROADMAP.md for a summary of what's currently being worked on.

These steps are for working on Atomic Testing (this monorepo), not for using it in your own project — for that, see Add Atomic Testing to your project above.

1. Install Node.js (v22.12 or newer) and pnpm (v10 or newer).

2. Install the dependencies:

   pnpm install

Pull requests are welcome. Before submitting, run:

pnpm run check:type
pnpm run check:lint
pnpm run check:style
pnpm test:dom
pnpm test:e2e

See CONTRIBUTING.md for full contribution guidelines, including dev setup and commit message conventions. For reporting a security vulnerability, see SECURITY.md.