Skip to main content

Atomic Testing

NPM version NPM license

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/.

Packages​

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.

Stability & version support policy​

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.

MUI driver majors​

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.

Driver familySupported majorsEnd of support
MUI (core)v6, v7, v9v5 - ended 2026-06-27
MUI-Xv6, v7, v8, v9v5 - ended 2026-06-27

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 are frozen at 0.81.0: they remain installable at that version but receive no fixes, new drivers, or CI/e2e coverage, and their test suites no longer run. 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.

Getting Started​

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

  2. Install the dependencies:

    pnpm install

  3. Add the packages you need to your project. A minimal setup might include the core and React packages:

    pnpm add @atomic-testing/core @atomic-testing/react-18

    Additional component drivers can be installed in the same way, for example:

    pnpm add @atomic-testing/component-driver-html

  4. Define your scene parts, create a test engine using the adapter for your framework, and write tests that interact with the scene.

For detailed guides and examples, see the online documentation.

Contributing​

Pull requests are welcome. Before submitting, run the checks defined in the root package.json:

pnpm run check:lint
pnpm run check:style
pnpm run check:types