{"id":14556,"library":"esdoc2-integrate-test-plugin","title":"ESDoc2 Integrate Test Plugin","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/esdoc2/esdoc2-plugins","tags":["javascript","esdoc2","test","plugin"],"install":[{"cmd":"npm install esdoc2-integrate-test-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esdoc2-integrate-test-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esdoc2-integrate-test-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin specifically designed to extend the functionality of esdoc2 and requires it as its core documentation engine.","package":"esdoc2","optional":false}],"imports":[],"quickstart":{"code":"// esdoc.config.js\n/**\n * @type {import('esdoc2').Config}\n */\nmodule.exports = {\n  // Source directory for your main application code\n  source: './src',\n  // Destination directory for the generated documentation\n  destination: './docs',\n  // Array of plugins to extend ESDoc2's functionality\n  plugins: [\n    {\n      // Name of the integration test plugin\n      name: 'esdoc2-integrate-test-plugin',\n      // Options specific to this plugin\n      option: {\n        // Source directory for your integration test files\n        source: './test/',\n        // List of global test interfaces to recognize and link (e.g., from Mocha, Jest)\n        interfaces: ['describe', 'it', 'context', 'suite', 'test'],\n        // Regex patterns to include specific test files\n        includes: ['(spec|Spec|test|Test)\\\\.js$', '(integration|e2e)\\\\.ts$'],\n        // Regex patterns to exclude specific test files (e.g., configuration files)\n        excludes: ['\\\\.config\\\\.js$', '\\\\.fixture\\\\.js$']\n      }\n    }\n  ]\n};\n\n// To run this configuration, save it as `esdoc.config.js` in your project root\n// and execute: `npx esdoc2` in your terminal.","lang":"javascript","description":"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."},"warnings":[{"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.","tags":["ESDoc2","configuration","testing"],"message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always provide a `source` path to your test files, e.g., `\"option\": { \"source\": \"./test/\" }`.","tags":["configuration","breaking change"],"message":"The `source` option within the plugin's configuration is mandatory. Omitting it will prevent the plugin from locating your integration test files.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","tags":["regex","configuration","file matching"],"message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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\"]`.","tags":["testing frameworks","configuration"],"message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","tags":["installation","configuration","plugin loading"],"cause":"esdoc2 could not find the plugin package or there was an error in its configuration.","error":"Error: The plugin 'esdoc2-integrate-test-plugin' could not load."},{"fix":"Add a `source` property with a valid path to your test files, e.g., `\"option\": { \"source\": \"./test/\" }`.","tags":["configuration","missing option"],"cause":"The `source` option for the `esdoc2-integrate-test-plugin` within its `option` object is missing or null.","error":"TypeError: Cannot read property 'source' of undefined"},{"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.","tags":["file matching","regex","configuration"],"cause":"The `includes` or `excludes` regular expressions are incorrectly configured, preventing the plugin from identifying your test files.","error":"Some test files are not appearing in my documentation."}],"ecosystem":"npm"}