Bundling Tests

Relevant source files

The bundling test system validates that the MUI packages integrate correctly with a variety of popular JavaScript bundlers and meta-frameworks. This ensures that the published packages can be consumed successfully in real-world applications built using tools like Vite, Webpack, esbuild, Next.js, and Gatsby. The system works by packaging the MUI packages locally and installing them into minimal test fixtures that simulate the experience of end users installing them from npm.

This test system is integral to the continuous integration workflow and complements unit and browser testing by catching integration issues related to bundler compatibility, missing exports, or incorrect dependency resolutions that are often only discovered during bundling/load time.

For a broader context on CI/CD, see CircleCI Configuration For insights into the build process that produces the tested artifacts, see Build Pipeline

System Overview

The bundling test system is implemented as a dedicated CircleCI workflow named bundling. It performs the following core sequence:

Build all MUI packages from source — compiling each package to distributable form.
Pack packages into .tgz archives — simulating npm packages.
Install these packages into isolated test fixture projects — minimal apps for different bundlers.
Execute each fixture's build and integration tests — to verify bundling correctness and runtime functionality.

This safeguards against integration regressions that normal unit or static tests cannot detect.

Bundling Test Workflow Architecture

The workflow consists of a preparation phase followed by parallel tests across different bundler fixtures.

This workflow guarantees that all bundler tests run against the exact same build outputs.

Sources: .circleci/config.yml306-320 .circleci/config.yml545-586

Test Preparation Job

The test_bundling_prepare CircleCI job executes the preparation phase:

Checkout the repository at the current commit.
Install dependencies for the monorepo.
Build all scoped packages using the Lerna script: pnpm lerna run --scope "@mui/*" build.
Pack packages into .tgz files via pnpm release:pack, simulating npm package tarballs.
Persist the packed files in the workspace under the packed/ directory for downstream access.

The artifact directory structure looks like:

packed/
├── @mui/material.tgz
├── @mui/icons-material.tgz
├── @mui/lab.tgz
├── @mui/styled-engine.tgz
├── @mui/system.tgz
├── @mui/utils.tgz
└── ... (other packages)

This setup avoids redundant builds in parallel test jobs.

Sources: .circleci/config.yml306-320

Bundler-Specific Test Jobs

The individual bundling tests for each bundler run in independent jobs that depend on test_bundling_prepare. They share a common structure:

Step	Description
`checkout`	Checks out the source code
`attach_workspace`	Restores the `packed/*.tgz` files to the job workspace
`install-deps`	Runs `pnpm install` within the fixture directory
`pnpm start`	Runs the fixture’s build and integration test script

Key: pnpm `ignore-workspace`

The install-deps step uses ignore-workspace: true. This disables the automatic workspace protocol resolution (workspace:*) during install, forcing pnpm to honor the overrides defined in package.json. Thus, the dependencies resolve to the locally packed tarballs rather than packages in the monorepo [.circleci/config.yml:71-71].

Working Directory Setup

Each job runs in the fixture directory:

/tmp/material-ui/test/bundling/fixtures/{fixture-name}/

This ensures pnpm install reads the correct package.json with bundler-specific overrides:

Sources: .circleci/config.yml321-460

Test Fixtures

Fixtures under test/bundling/fixtures/ are minimal applications configured to test MUI integration with different bundlers and frameworks. Each fixture contains:

A package.json listing dependencies and overrides pointing to packed .tgz files.
Bundler-specific configuration files (e.g., vite.config.js, esbuild.fixture.js).
Minimal React or Node.js source code importing MUI components.
Integration test scripts (e.g., testViteIntegration.js) that launch browsers and verify MUI components render without error.
Scripts to build, serve, and test the app in CI.

Using pnpm overrides to test local packages

Example from the Vite fixture package.json shows dependencies targeting workspace packages overridden by local .tgz archives:

This key mechanism allows validating that the packages as published work correctly in real dependency graphs [test/bundling/fixtures/vite/package.json:30-39], [test/bundling/fixtures/next-webpack5/package.json:26-35], [test/bundling/fixtures/esbuild/package.json:31-40].

Sample fixture start scripts

Most fixtures define a prestart step that generates required source files and a start command that runs the build and integration test concurrently. For example, Vite:

The concurrently package runs both the server and tests in parallel, succeeding when the test passes and terminating the other. Similar patterns exist for esbuild, Next.js, Gatsby, and others [test/bundling/fixtures/vite/package.json:5-9], [test/bundling/fixtures/esbuild/package.json:6-10], [test/bundling/fixtures/next-webpack5/package.json:6-7], [test/bundling/fixtures/gatsby/package.json:6-8].

Sources: test/bundling/fixtures/vite/package.json test/bundling/fixtures/next-webpack5/package.json test/bundling/fixtures/esbuild/package.json test/bundling/fixtures/gatsby/package.json

Tested Bundlers and Frameworks

The suite covers a broad spectrum of popular bundlers and frameworks:

CircleCI Job	Bundler / Framework	Version Info	Purpose & Focus
`test_bundling_vite`	Vite	5.4.21	ESM bundling & fast dev server
`test_bundling_next_webpack4`	Next.js with Webpack 4	14.2.35 (React 17)	Legacy Next.js & Webpack 4 support
`test_bundling_next_webpack5`	Next.js with Webpack 5	14.2.35 (React 18)	Modern Next.js & Webpack 5 support
`test_bundling_create_react_app`	Create React App	-	Webpack-based CRA apps
`test_bundling_esbuild`	esbuild	0.25.0	Native super-fast bundler
`test_bundling_gatsby`	Gatsby	5.13.7	Static site generation
`test_bundling_snowpack`	Snowpack	3.8.8	Unbundled dev mode
`test_bundling_node_cjs`	Node.js CommonJS	-	Test CJS module resolution
`test_bundling_node_esm`	Node.js ESM	-	Test ESM package resolution

Sources: test/bundling/fixtures/vite/package.json23 test/bundling/fixtures/next-webpack4/package.json19 test/bundling/fixtures/next-webpack5/package.json17 test/bundling/fixtures/esbuild/package.json21 test/bundling/fixtures/gatsby/package.json19 test/bundling/fixtures/snowpack/package.json20

Framework-specific Nuances

Gatsby: Uses the mui-node-browser executor with the environment variable GATSBY_CPU_COUNT: '3'. This limits parallelism to avoid build resource starvation in CI [.circleci/config.yml:448-460].
esbuild: Runs in a plain official Playwright container mcr.microsoft.com/playwright:v1.58.2-noble, not the custom executor [.circleci/config.yml:430-442].
Next.js Webpack 4: Applies NODE_OPTIONS=--openssl-legacy-provider due to compatibility issues with OpenSSL 3.0+ [test/bundling/fixtures/next-webpack4/package.json:7].

Workflow Orchestration

The bundling workflow is triggered conditionally in CircleCI when the workflow parameter is set to "bundling". It orchestrates jobs as follows:

All bundler test jobs specify:

ensuring that all tests use the same built and packed artifacts.

Sources: .circleci/config.yml545-586

Integration Test Implementation

Each bundling fixture includes a corresponding integration test script, usually named in the form test{Bundler}Integration.js.

Typical Test Flow

Launch a Playwright browser instance.
Navigate to the locally served bundled app (e.g., port 5001).
Assert that MUI components render without console errors.
Validate runtime behavior and interactions.

Running Tests Concurrently

Fixtures use concurrently to run the bundler's build and server alongside the test script. For example, the Vite fixture runs:

Here:

pnpm vite build bundles the app.
pnpm server serves the built files on port 5001.
node testViteIntegration runs Playwright integration tests.
The --success first flag marks success if any process exits successfully (test passing).
--kill-others halts remaining processes to clean up.

This pattern ensures tests run in CI reliably and terminate correctly.

Sources: test/bundling/fixtures/vite/package.json5-8 test/bundling/fixtures/vite/package.json25-29

Manual Workflow Triggering

The bundling workflow is not triggered on every commit but can be run manually through CircleCI’s web interface or API by selecting workflow: bundling. This allows targeted validation of package builds against potential bundling issues before merging changes.

Setting the workflow parameter at the pipeline level controls which workflow runs. When set to "bundling", only this workflow executes, skipping unit and other tests.

Sources: .circleci/config.yml7-15 .circleci/config.yml545-547

Summary Diagram

Code Entity Mapping

References

.circleci/config.yml lines 306-320, 321-460, 430-460, 545-586
test/bundling/fixtures/vite/package.json lines 5-9, 23-39
test/bundling/fixtures/next-webpack4/package.json lines 1-39
test/bundling/fixtures/next-webpack5/package.json lines 1-37
test/bundling/fixtures/esbuild/package.json lines 5-41
test/bundling/fixtures/gatsby/package.json lines 1-39
test/bundling/fixtures/snowpack/package.json lines 1-41

Sources: Multiple files as cited above.