{"id":13185,"library":"find-test-names","title":"Find Test Names","description":"find-test-names is a JavaScript utility library designed to parse Mocha and Cypress test specification files to extract suite and test names, including associated tags and structural hierarchy. Currently at version 1.29.19, it maintains a steady release cadence with frequent minor updates, primarily for dependency bumps and bug fixes. The library differentiates itself by offering deep static analysis of test files, supporting advanced features like effective tag computation (propagating tags from parent suites to child tests), filtering tests by tags, and extracting pending tests. It handles modern JavaScript features, including JSX and TypeScript syntax, by leveraging `@babel/parser`. This enables automation scenarios where understanding test metadata without executing the tests is crucial, such as dynamic test selection or reporting.","status":"active","version":"1.29.19","language":"javascript","source_language":"en","source_url":"https://github.com/bahmutov/find-test-names","tags":["javascript","mocha","cypress","tests"],"install":[{"cmd":"npm install find-test-names","lang":"bash","label":"npm"},{"cmd":"yarn add find-test-names","lang":"bash","label":"yarn"},{"cmd":"pnpm add find-test-names","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for parsing JavaScript and TypeScript code to extract test and suite names and their associated metadata.","package":"@babel/parser","optional":false},{"reason":"Used for internal debugging messages.","package":"debug","optional":true},{"reason":"Used for globbing file paths, especially when reading files from disk via methods like `findEffectiveTestTagsIn`.","package":"tinyglobby","optional":false}],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the recommended modern approach. The library supports both.","wrong":"const { getTestNames } = require('find-test-names')","symbol":"getTestNames","correct":"import { getTestNames } from 'find-test-names'"},{"note":"Used to compute and apply inherited tags throughout the test structure. Available as a named export.","wrong":"const { setEffectiveTags } = require('find-test-names')","symbol":"setEffectiveTags","correct":"import { setEffectiveTags } from 'find-test-names'"},{"note":"This function can accept source code directly or operate on the structure array returned by `getTestNames` after `setEffectiveTags` has been applied.","wrong":"const filterByEffectiveTags = require('find-test-names').filterByEffectiveTags","symbol":"filterByEffectiveTags","correct":"import { filterByEffectiveTags } from 'find-test-names'"},{"note":"This utility directly reads a file from disk and returns effective tags without manual parsing steps.","wrong":"require('find-test-names').findEffectiveTestTagsIn('file.js')","symbol":"findEffectiveTestTagsIn","correct":"import { findEffectiveTestTagsIn } from 'find-test-names'"}],"quickstart":{"code":"import { getTestNames, setEffectiveTags, filterByEffectiveTags } from 'find-test-names';\nimport * as fs from 'node:fs/promises';\n\nasync function analyzeSpecFile(filename) {\n  const source = `\n    describe('Feature A', { tags: '@featureA' }, () => {\n      describe('Sub-feature B', { tags: '@subFeatureB' }, () => {\n        it('should do something important', { tags: ['@smoke', '@critical'] }, () => {\n          // test implementation\n        });\n        it('should handle edge cases', () => {\n          // another test\n        });\n      });\n      it.skip('should be skipped for now', () => {});\n    });\n    it('standalone test', { requiredTags: ['@data'] }, () => {});\n  `;\n  \n  console.log(`Analyzing a mock spec file:\\n${source}\\n`);\n\n  // Get the full structure including suite and test names\n  const resultWithStructure = getTestNames(source, true);\n  console.log('Raw structure:', JSON.stringify(resultWithStructure.structure, null, 2));\n\n  // Compute effective tags for each test\n  setEffectiveTags(resultWithStructure.structure);\n  console.log('\\nStructure with effective tags:', JSON.stringify(resultWithStructure.structure, null, 2));\n\n  // Filter tests by a specific effective tag\n  const smokeTests = filterByEffectiveTags(resultWithStructure.structure, ['@smoke']);\n  console.log('\\nTests with @smoke tag:', smokeTests.map(t => t.fullTitle));\n\n  const allTests = getTestNames(source);\n  console.log('\\nSimple list of test names:', allTests.testNames);\n}\n\nanalyzeSpecFile('mock.spec.js').catch(console.error);\n","lang":"typescript","description":"Demonstrates parsing a test file, extracting its full structure, computing effective tags for each test, and filtering tests by specific tags. It also shows the simpler flat list extraction."},"warnings":[{"fix":"Ensure your Node.js and `find-test-names` versions are up-to-date. If errors persist with new syntax, consider slightly older syntax or a custom Babel configuration if the library allowed (which it currently does not for parsing).","message":"The library relies on `@babel/parser` for static analysis. Support for the absolute latest JavaScript/TypeScript syntax may lag slightly behind Babel's releases. If parsing fails with a `SyntaxError`, it might indicate unsupported bleeding-edge syntax or a need to update `find-test-names` to a version with a newer Babel parser dependency.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use string literals directly for tags or ensure tag variables are local `const` declarations and used via direct reference or literal property access (e.g., `{ tags: MY_TAG }` or `{ tags: TAGS.FOO }`).","message":"When defining test tags using variables, `find-test-names` currently only supports local `const` declarations or literal property access on local `const` objects within the same file. It cannot resolve arbitrary dynamic expressions or imported variables for tag values, which will result in those tags not being extracted.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For full traceability, use string literals for test titles. If dynamic names are necessary, be aware of the `<unknown test>` label and rely on other metadata like tags for identification.","message":"Test names derived from variables (e.g., `it(myTestName, ...)`) will be extracted as `<unknown test>`. While tags for such tests are still extracted, the specific name cannot be resolved statically.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review any file globbing patterns used with `findEffectiveTestTagsIn` or similar file-system-interacting functions if unexpected changes in file discovery occur after updating to `v1.29.19`.","message":"Version 1.29.19 switched from a previous globbing library to `tinyglobby`. While intended as a bug fix and improvement, this change could potentially alter file matching behavior in subtle ways for users relying on specific edge cases of the previous glob implementation, though this is unlikely for most standard use cases.","severity":"breaking","affected_versions":"1.29.19"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update `find-test-names` to the latest version. If the error persists, check if the syntax is extremely new or non-standard. Consider simplifying the problematic code segment or reporting an issue to the library maintainers.","cause":"The test spec file contains JavaScript/TypeScript syntax that the embedded `@babel/parser` version does not yet support or has trouble interpreting due to misconfiguration.","error":"SyntaxError: Unknown word (or similar Babel parsing error)"},{"fix":"Ensure you are using named imports/requires: `import { getTestNames } from 'find-test-names'` for ESM or `const { getTestNames } = require('find-test-names')` for CommonJS.","cause":"Attempting to use `getTestNames` as a default export or incorrectly destructuring named exports in CommonJS or ESM environments.","error":"TypeError: getTestNames is not a function"},{"fix":"Always use `import { ... } from 'find-test-names'` in ESM projects. Ensure Node.js version supports package `exports` map (Node.js 12+). Check `package.json` for `\"type\": \"module\"` and correct import syntax.","cause":"Project is configured for ESM (`\"type\": \"module\"` in `package.json`), but the `require` statement or import path is incorrect for an ESM context, or the package's `exports` map isn't properly resolved.","error":"Error: Cannot find module 'find-test-names' or similar module resolution error in an ESM project."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}