Registry / testing / esdoc2-integrate-test-plugin

esdoc2-integrate-test-plugin

library2.0.0jsnpmunverified

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.

testing

npm install esdoc2-integrate-test-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · ESDOC2-INTEGRATE-T

esdoc2-integrate-test-plugin

testingjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

Debug

Known issues

gotchaThe 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.

affects: >=2.0.0

breakingThe `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/" }`.

affects: >=2.0.0

gotchaRegex 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.

affects: >=2.0.0

gotchaThe `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"]`.

affects: >=2.0.0

Errors

Common errors & fixes

Error: The plugin 'esdoc2-integrate-test-plugin' could not load.

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

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.

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.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

esdoc2requiredThis package is a plugin specifically designed to extend the functionality of esdoc2 and requires it as its core documentation engine.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/esdoc2/esdoc2-plugins ↗

packagehttps://www.npmjs.com/package/esdoc2-integrate-test-plugin ↗