Test utils for theforeman

Usage no npm install needed!

<script type="module">
  import theforemanTest from 'https://cdn.skypack.dev/@theforeman/test';



Adds theforeman testing tools to you project.

Package Version Downloads Status Build Status: Linux PRs Welcome code style: prettier


npm install --save-dev @theforeman/test
  1. Use tfm-test and tfm-publish-coverage (for coverage) scripts under test and publish-coverage respectively in package.json:
  "test": "tfm-test --plugin",
  "publish-coverage": "tfm-publish-coverage"

This script accepts all jest's arguments, including plugin which is a flag indicator for plugins.


In order to extend general settings or creating global mocks, create a test_setup.js file under /webpack directory

For example, some global mocks :

// test_setup.js
jest.mock("./assets/javascripts/foreman_tools", () => ({
  foremanUrl: url => url


This package gives an opiniated approach for test configurations and tools, including jest, enzyme, react-testing-library, and a test utils library.

These functions can be imported directly from @theforeman/test: mount and shallow- which are from enzyme testComponentSnapshotsWithFixtures testReducerSnapshotWithFixtures, testActionSnapshotWithFixtures testSelectorsSnapshotWithFixtures, IntegrationTestHelper - which are from react-redux-test-utils MockAdapter - which is from axios-mock-adapter and also adding coveralls for coverage.

jest docs

enzyme docs

react-testing-library docs


Unit testing

You can use testComponentSnapshotsWithFixtures for a unit testing without redux. Keep in mind to import unconnected component (wrapped by connect nor redux-hooks)

/* UserProfile.test.js */
import { testComponentSnapshotsWithFixtures } from "@theforeman/test";
import UserProfile from "../UserProfile"; // not redux connected

const fixtures = {
  "should render UserProfile": {
    user: "some-user"
  "should render UserProfile with avatar": {
    user: "some-user",
    showAvatar: true
  "should render UserProfile with posts and photos": {
    user: "some-user",
    showPosts: true,
    showPhotos: true

describe("UserProfile - component", () =>
  testComponentSnapshotsWithFixtures(UserProfile, fixtures));

Redux's Actions

This will create a snapshot for UserProfileActions.js actions file:

/* UserProfileActions.test.js */
import { testActionSnapshotWithFixtures } from '@theforeman/test';
import {
} from "../UserProfileActions";

const fixtures = {
  "should update-show-avatar": () => updateShowAvatar(true),
  "should update-show-posts": () => updateShowPosts(true),
  "should update-show-photos": () => updateShowPhotos(true)

describe("UserProfile - Actions", () =>

For async actions and further explanation please look here

Redcuer's Testing

testReducerSnapshotWithFixtures creates a snapshot of a given reducer and fixtures:

/* LoginFormReducer.test.js */
import { testReducerSnapshotWithFixtures } from '@theforeman/test';
import {
} from '../LoginFormConstants';

import reducer from '../LoginFormReducer';

const fixtures = {
  'it should update username': {
      action: {
        payload: { username: 'some-username' }
  'it should update password': {
    action: {
      payload: { password: 'some-password' }
  'it should toggle remember-me': {
    state: { rememberMe: false },
    action: {

describe('LoginForm - Reducer', () =>
  testReducerSnapshotWithFixtures(reducer, fixtures));

Integration testing

This test a full cycle of a component including redux (actions, reducers and store)

/* __tests__/integration.test.js */
import React from 'react';
import { IntegrationTestHelper } from '@theforeman/test';

import UserProfile, { reducers } from '../index'; // This is a connected component

describe('UserProfile - Integration Test', () => {
  it('should flow', () => {
    const integrationTestHelper = new IntegrationTestHelper(reducers);

    const component = integrationTestHelper.mount(
      <UserProfile user="some-user" />

    // The user-avatar should not be shown
    integrationTestHelper.takeStoreSnapshot('initial state');

    // trigger checkbox change
      .simulate('change', { target: { checked: true } });

    // The user-avatar should be shown now
      'Update to show the user-avatar'

Functional Testing

The package react-testing-library is included and is a way to test functionality in a React application from a user perspective rather than testing the implementation. To use this library, please see the official documentation. It can be imported directly from @testing-library/react.

This approach is flexible and can be used to test smaller components as well as full pages made up of many components. For functional testing, it is recommended to test components connected to redux and mock the http calls, allowing the component to function as it does in the production application. These tests also tend to be less brittle than other approaches and can be good at catching regressions when refactoring.

For an example of how this is library is used within the Foreman ecosystem, please see Katello's react-testing-library-wrapper


Please checkout the contributing.md, the roadmap.md and the open issues.