{"id":13209,"library":"fusion-test-utils","title":"FusionJS Testing Utilities","description":"fusion-test-utils provides a comprehensive suite of testing utilities specifically designed for FusionJS applications. It simplifies the process of unit and integration testing FusionJS components, plugins, and entire applications by offering tools to create isolated test environments, mock dependencies within the FusionJS DI system, and simulate application lifecycle events. The current stable version is 2.6.2. While `fusion-test-utils` itself has a less frequent direct release cycle, it is part of the broader FusionJS ecosystem which sees active development, with various core and plugin packages updated every few weeks. Its key differentiator is deep integration with FusionJS's architecture, enabling idiomatic and robust testing without significant boilerplate, unlike trying to adapt general-purpose testing libraries.","status":"active","version":"2.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/fusionjs/fusionjs","tags":["javascript","typescript"],"install":[{"cmd":"npm install fusion-test-utils","lang":"bash","label":"npm"},{"cmd":"yarn add fusion-test-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add fusion-test-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"TypeScript type definitions for Jest, a common testing framework used with FusionJS applications.","package":"@types/jest","optional":true},{"reason":"TypeScript type definitions for Node.js, essential for development environments and server-side testing.","package":"@types/node","optional":true},{"reason":"The core FusionJS framework is a peer dependency, providing the fundamental application context and DI system for which these utilities are designed.","package":"fusion-core","optional":false}],"imports":[{"note":"Primarily designed for ESM environments, though CommonJS `require` might work with transpilation. Best practice is named import.","wrong":"const createTestApp = require('fusion-test-utils').createTestApp","symbol":"createTestApp","correct":"import { createTestApp } from 'fusion-test-utils'"},{"note":"The `render` utility is a named export, not a default export from a subpath.","wrong":"import render from 'fusion-test-utils/render'","symbol":"render","correct":"import { render } from 'fusion-test-utils'"},{"note":"Used for retrieving the Virtual DOM element from a rendered component. Note the camelCase convention.","wrong":"import { getVdomElement as getVDOMElement } from 'fusion-test-utils'","symbol":"get-vdom-element","correct":"import { getVdomElement } from 'fusion-test-utils'"}],"quickstart":{"code":"import { createTestApp, render } from 'fusion-test-utils';\nimport App from './src/main'; // Assuming your main FusionJS App entry\nimport { ServiceWorker } from 'fusion-plugin-service-worker';\nimport { RPC } from 'fusion-plugin-rpc';\n\ndescribe('My FusionJS App', () => {\n  let app;\n\n  beforeEach(() => {\n    app = createTestApp(App, {\n      plugins: [\n        [ServiceWorker, { defer: true }], // Example plugin setup\n        RPC, // Another example plugin\n      ],\n      modules: [],\n      middleware: [],\n    });\n  });\n\n  afterEach(async () => {\n    if (app) {\n      await app.teardown(); // Clean up the app instance\n    }\n  });\n\n  it('renders without crashing', async () => {\n    const rendered = await render(app);\n    expect(rendered.html()).toContain('<div>Hello FusionJS</div>'); // Assuming your App renders this\n  });\n\n  it('handles route changes correctly', async () => {\n    // Example: test a route specific component\n    // You might need to mock or setup fusion-plugin-react-router for this\n    const rendered = await render(app, '/some-path');\n    expect(rendered.html()).toContain('Path Specific Content');\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Review 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.","message":"FusionJS 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`).","severity":"breaking","affected_versions":">=2.7.0 (fusion-core), >=2.35.0 (fusion-cli), packages consuming fusion-test-utils."},{"fix":"Always use `async/await` for tests involving asynchronous code. Example: `it('...', async () => { await render(app); expect(...); });`","message":"When 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.","severity":"gotcha","affected_versions":"*"},{"fix":"When 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.","message":"Mocking 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.","severity":"gotcha","affected_versions":"*"},{"fix":"Align 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.","message":"Older 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.","severity":"deprecated","affected_versions":"<2.6.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Review 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.","cause":"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`).","error":"TypeError: Cannot read properties of undefined (reading 'of')"},{"fix":"Implement 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.","cause":"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.","error":"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."},{"fix":"Ensure 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.","cause":"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.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}