ESDoc2 Integrate Test Plugin

2.0.0 · active · verified Sun Apr 19

This package, `esdoc2-integrate-test-plugin`, functions as a specialized plugin for the ESDoc2 documentation generator. Its primary purpose is to seamlessly embed and link integration test documentation directly into the output generated by ESDoc2. Users configure the plugin within their `esdoc2` setup to specify the source directories containing test files, define recognized testing interfaces (such as `describe`, `it`, `context`, `suite`, and `test`), and apply include/exclude regex patterns to precisely control which test files are processed. The plugin is currently on version 2.0.0, with a recent feature release (v2.1.0) indicating ongoing maintenance and development. Its key differentiator lies in enabling comprehensive documentation that cross-references code with its corresponding integration tests, enhancing clarity for maintainers and consumers of the documented codebase. The release cadence appears feature-driven, providing updates as new capabilities are added or existing ones are refined.

Common errors

```
Error: The plugin 'esdoc2-integrate-test-plugin' could not load.
```
cause esdoc2 could not find the plugin package or there was an error in its configuration.

fix Ensure `esdoc2-integrate-test-plugin` is installed (`npm install esdoc2-integrate-test-plugin`) and correctly referenced by name in your `esdoc2` configuration's `plugins` array.
```
TypeError: Cannot read property 'source' of undefined
```
cause The `source` option for the `esdoc2-integrate-test-plugin` within its `option` object is missing or null.

fix Add a `source` property with a valid path to your test files, e.g., `"option": { "source": "./test/" }`.
```
Some test files are not appearing in my documentation.
```
cause The `includes` or `excludes` regular expressions are incorrectly configured, preventing the plugin from identifying your test files.

fix Review the `includes` and `excludes` patterns in your `esdoc2` configuration to ensure they correctly match the filenames and paths of your integration tests. Use online regex testers to validate.

Warnings

gotcha The plugin requires `esdoc2` to be installed and configured in your project. This plugin does not run tests itself but rather integrates the *documentation* of your tests into ESDoc2.
Fix: Ensure `esdoc2` is installed (`npm install esdoc2`) and your project has a working ESDoc2 configuration file. The plugin integrates test file content, not test execution.
breaking The `source` option within the plugin's configuration is mandatory. Omitting it will prevent the plugin from locating your integration test files.
Fix: Always provide a `source` path to your test files, e.g., `"option": { "source": "./test/" }`.
gotcha Regex patterns for `includes` and `excludes` must be correctly formatted JavaScript regular expressions. Incorrect patterns can lead to test files being missed or incorrect files being included.
Fix: Thoroughly test your `includes` and `excludes` regex patterns to ensure they match your desired file naming conventions. Examples: `"(spec|Spec|test|Test)\\.js$"` for common test file suffixes.
gotcha The `interfaces` option defines the global test functions (like `describe`, `it`) that the plugin recognizes. If you use custom test framework functions or aliases, you must add them to this list.
Fix: Review your testing framework's global functions and update the `interfaces` array if your tests use names not in the default list `["describe", "it", "context", "suite", "test"]`.

Install

npm install esdoc2-integrate-test-plugin npm
yarn add esdoc2-integrate-test-plugin yarn
pnpm add esdoc2-integrate-test-plugin pnpm

Quickstart

This configuration snippet shows how to integrate `esdoc2-integrate-test-plugin` into your ESDoc2 documentation generation process by specifying test file locations, testing interfaces, and regex patterns for including/excluding files.

// esdoc.config.js
/**
 * @type {import('esdoc2').Config}
 */
module.exports = {
  // Source directory for your main application code
  source: './src',
  // Destination directory for the generated documentation
  destination: './docs',
  // Array of plugins to extend ESDoc2's functionality
  plugins: [
    {
      // Name of the integration test plugin
      name: 'esdoc2-integrate-test-plugin',
      // Options specific to this plugin
      option: {
        // Source directory for your integration test files
        source: './test/',
        // List of global test interfaces to recognize and link (e.g., from Mocha, Jest)
        interfaces: ['describe', 'it', 'context', 'suite', 'test'],
        // Regex patterns to include specific test files
        includes: ['(spec|Spec|test|Test)\\.js$', '(integration|e2e)\\.ts$'],
        // Regex patterns to exclude specific test files (e.g., configuration files)
        excludes: ['\\.config\\.js$', '\\.fixture\\.js$']
      }
    }
  ]
};

// To run this configuration, save it as `esdoc.config.js` in your project root
// and execute: `npx esdoc2` in your terminal.

view raw JSON →