Frontend Test Framework

Common errors

• ReferenceError: regeneratorRuntime is not defined

  cause Modern JavaScript features like `async/await` require polyfills, which might be missing or incorrectly configured in the test environment.
  fix Ensure `regenerator-runtime` is installed (`npm i regenerator-runtime -D`) and imported in your Jest `setupFiles` (e.g., `import 'regenerator-runtime/runtime';`) or configure Babel to include `@babel/plugin-transform-runtime`.

• SyntaxError: Unexpected token 'export' (when running tests for a node_modules package)

  cause A dependency within `node_modules` is using ES module syntax which Jest's default transformer, configured by `yhtml5-test`, is ignoring.
  fix Modify the `transformIgnorePatterns` array in your `.config.js` to explicitly include the problematic `node_modules` package for Babel transformation.

• Cannot find module 'src/path/to/module'

  cause Webpack aliases defined for the application are not being resolved correctly by Jest's module loader.
  fix Verify that your `moduleNameMapper` in `.config.js` accurately reflects your Webpack aliases, mapping them to the correct absolute paths.

• console.error: Warning: React.render is no longer supported in React 16+

  cause Incompatible major versions of React, `react-test-renderer`, or `enzyme` are being used. The quickstart specifies older versions (React 15.x, Enzyme 2.x).
  fix Update `react-test-renderer` and `enzyme` to versions compatible with your project's React major version (e.g., `enzyme@3.x` with `enzyme-adapter-react-16` for React 16+), and ensure the adapter is configured in `setupTestFrameworkScriptFile`.

Warnings

• breaking The quickstart dependencies explicitly list older versions of `react-test-renderer@15.6.x` and `enzyme@2.9.x`. These versions are incompatible with React 16+ and will require significant updates.
  Fix: For React 16+ projects, upgrade `enzyme` to v3.x and install a compatible React adapter (e.g., `enzyme-adapter-react-16`). You may also need to update `@2dfire/2dfire-scripts`.
• gotcha The framework's configuration (`.config.js`) must use CommonJS `module.exports` syntax. Attempting to use ES module `export default` will result in a configuration loading error.
  Fix: Ensure your `.config.js` file correctly uses `module.exports = config` to expose its configuration object.
• gotcha The `transformIgnorePatterns` in `.config.js` might prevent necessary transpilation for some `node_modules` packages, especially modern libraries published as ES modules, leading to `SyntaxError`s.
  Fix: Modify the `transformIgnorePatterns` regex in your `.config.js` to explicitly include specific `node_modules` packages that need Babel processing.
• gotcha Test files may not be discovered if their naming conventions or locations do not align with the default or custom `testMatch` patterns configured in `.config.js`.
  Fix: Adhere to standard Jest conventions (`__tests__/**/*.js?(x)`, `*.test.js`, `*.spec.js`), or adjust the `testMatch` array in your `.config.js` to match your project's structure.
• gotcha This package is a wrapper for `@2dfire/2dfire-scripts`. Direct `npm install yhtml5-test` does not install the primary CLI executable. Users must install `@2dfire/2dfire-scripts` as a dev dependency to run tests.
  Fix: Always ensure `@2dfire/2dfire-scripts` is installed as a `devDependency` and refer to its documentation for deeper configuration or troubleshooting.

Install

• npm install yhtml5-test npm
• yarn add yhtml5-test yarn
• pnpm add yhtml5-test pnpm

Imports

• CLI Test Commands
  wrong:

  import { test } from 'yhtml5-test'

  correct:

  npm test
  npm run test:c
  npm run test:u

  This package is a CLI test runner; direct interaction is via npm scripts that invoke '2dfire-scripts'.
• Configuration Object
  wrong:

  // .config.js
  export default config;

  correct:

  // .config.js
  const path = require('path');
  module.exports = config;

  Configuration files are loaded using Node.js CommonJS `require()`, not ES module `export` syntax.
• Test File Imports
  wrong:

  const MyComponent = require('./MyComponent');

  correct:

  import { shallow } from 'enzyme';
  import MyComponent from './MyComponent';

  Inside test files, modern ES module `import` syntax is expected for importing source code and testing utilities.

Quickstart

This quickstart guides you through setting up `yhtml5-test` by adding required scripts to `package.json`, installing development dependencies, configuring `.config.js` for Jest and Webpack aliases, and writing a basic React component test using Enzyme and snapshot testing.

{
  "name": "my-react-app",
  "version": "1.0.0",
  "scripts": {
    "test": "2dfire-scripts test --env=jsdom",
    "test:c": "npm test -- --coverage",
    "test:u": "npm i @2dfire/2dfire-scripts@latest -D"
  },
  "devDependencies": {
    "@2dfire/2dfire-scripts": "latest",
    "react-test-renderer": "15.6.x",
    "enzyme": "2.9.x",
    "jest-enzyme": "3.8.x"
  }
}

// Create .config.js in your project root
// This configures webpack aliases and Jest transformers
// .config.js
const path = require('path');
const webpackConfigAlias = {
  '^src(.*)$': path.resolve(__dirname, 'src$1'),
};

const config = {
  test: {
    testMatch: ['<rootDir>/src/**/__tests__/**/*.js?(x)', '<rootDir>/src/**/?(*.)(spec|test).js?(x)'],
    transformIgnorePatterns: ["node_modules/(?!(yhtml5-test|react-redux|react-native-button)/)"],
    moduleNameMapper: webpackConfigAlias,
    collectCoverageFrom: ['src/**/*.{js,jsx}'],
  }
};

module.exports = config;

// Example test file: src/components/__tests__/MyComponent.test.js
import React from 'react';
import { shallow } from 'enzyme';
import MyComponent from '../MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    const wrapper = shallow(<MyComponent />);
    expect(wrapper).toMatchSnapshot();
  });

  it('displays the correct text', () => {
    const wrapper = shallow(<MyComponent text="Hello Test" />);
    expect(wrapper.find('h1').text()).toEqual('Hello Test');
  });
});