Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createTestApp
✓ import { createTestApp } from 'fusion-test-utils'
✗ const createTestApp = require('fusion-test-utils').createTestApp
Primarily designed for ESM environments, though CommonJS `require` might work with transpilation. Best practice is named import.
render
✓ import { render } from 'fusion-test-utils'
✗ import render from 'fusion-test-utils/render'
The `render` utility is a named export, not a default export from a subpath.
get-vdom-element
✓ import { getVdomElement } from 'fusion-test-utils'
✗ import { getVdomElement as getVDOMElement } from 'fusion-test-utils'
Used for retrieving the Virtual DOM element from a rendered component. Note the camelCase convention.
This quickstart demonstrates setting up a basic FusionJS test application using `createTestApp` and rendering a component with `render`. It includes `beforeEach` and `afterEach` hooks for proper test setup and teardown, and showcases simple assertions against the rendered output.
import { createTestApp, render } from 'fusion-test-utils';
import App from './src/main'; // Assuming your main FusionJS App entry
import { ServiceWorker } from 'fusion-plugin-service-worker';
import { RPC } from 'fusion-plugin-rpc';
describe('My FusionJS App', () => {
let app;
beforeEach(() => {
app = createTestApp(App, {
plugins: [
[ServiceWorker, { defer: true }], // Example plugin setup
RPC, // Another example plugin
],
modules: [],
middleware: [],
});
});
afterEach(async () => {
if (app) {
await app.teardown(); // Clean up the app instance
}
});
it('renders without crashing', async () => {
const rendered = await render(app);
expect(rendered.html()).toContain('<div>Hello FusionJS</div>'); // Assuming your App renders this
});
it('handles route changes correctly', async () => {
// Example: test a route specific component
// You might need to mock or setup fusion-plugin-react-router for this
const rendered = await render(app, '/some-path');
expect(rendered.html()).toContain('Path Specific Content');
});
});
Debug
Known issues
breakingFusionJS applications, including `fusion-test-utils` consumers, were updated to React 18. This upgrade introduces new features like concurrent rendering and hooks (`useTransition`, `useDeferredValue`), but also strict mode behaviors and changes to API calls (e.g., `ReactDOM.render` replaced by `createRoot`).fixReview the React 18 upgrade guide. Ensure all components are compatible with strict mode. Update any usage of `ReactDOM.render` in custom entry points or test setups to `createRoot`. Expect potential warnings about deprecated lifecycle methods.
affects: >=2.7.0 (fusion-core), >=2.35.0 (fusion-cli), packages consuming fusion-test-utils.
gotchaWhen testing async FusionJS logic (e.g., RPC calls, data fetching in lifecycle methods), ensure your tests `await` asynchronous operations and use Jest's `async/await` pattern or return promises. Failing to do so can lead to flaky tests or false positives.fixAlways use `async/await` for tests involving asynchronous code. Example: `it('...', async () => { await render(app); expect(...); });` affects: *
gotchaMocking FusionJS plugins or dependencies requires careful setup within `createTestApp`. If a plugin expects specific dependencies via DI and they are not provided or mocked correctly in the test app, it can lead to runtime errors or unexpected behavior.fixWhen using `createTestApp`, explicitly provide all necessary plugins and their configurations that your component or application under test relies on. Use `mock` or `noop` plugins for dependencies that are not relevant to the specific test case.
affects: *
deprecatedOlder versions of FusionJS plugins and `fusion-test-utils` might rely on older versions of Jest or other testing libraries. Regularly updating `jest` and `@types/jest` peer dependencies is crucial.fixAlign your `jest` and `@types/jest` versions with the recommendations in `fusion-cli` and `fusion-test-utils` peer dependencies. Check the FusionJS monorepo for recommended versions.
affects: <2.6.2
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'of')
Often occurs when a FusionJS plugin's dependencies are not correctly provided in the `createTestApp` setup, particularly for plugins that use the DI system (e.g., `fusion-core`'s `Token.of`).
fixReview the plugin dependencies required by the part of the application you are testing. Ensure all necessary plugins are included in the `createTestApp` configuration, even if mocked or set to a no-op implementation.
Error: Jest: a worker process has failed to exit gracefully and has been force exited. This is likely caused by tests not tearing down their setup correctly.
Commonly happens when FusionJS applications or plugins within tests are not properly torn down after each test, leaving open resources like server instances or event listeners.
fixImplement an `afterEach` hook that calls `await app.teardown()` on your `createTestApp` instance to ensure all resources are cleaned up. For server-side tests, explicitly close any HTTP servers or database connections.
SyntaxError: Cannot use import statement outside a module
Attempting to use ES module `import` syntax in a CommonJS environment, typically when Jest is not configured to transpile ES modules or when testing Node.js-only modules that haven't been transpiled.
fixEnsure your Jest configuration (`jest.config.js` or `package.json` `jest` field) correctly sets up Babel or `ts-jest` to transpile imported modules. Check `transformIgnorePatterns` to ensure `fusion-test-utils` and other FusionJS packages are not being ignored by Babel/TypeScript transformation.
Audit
Dependencies
@types/jestoptionalTypeScript type definitions for Jest, a common testing framework used with FusionJS applications.
@types/nodeoptionalTypeScript type definitions for Node.js, essential for development environments and server-side testing.
fusion-corerequiredThe core FusionJS framework is a peer dependency, providing the fundamental application context and DI system for which these utilities are designed.