Registry / testing / find-test-names

find-test-names

JSON →
library1.29.19jsnpmunverified

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.

npm install find-test-names
INSTALL
IMPORT
SIG · FIND-TEST-NAMES
F
find-test-names
testingjavascriptv1.29.19
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

getTestNames
import { getTestNames } from 'find-test-names'
const { getTestNames } = require('find-test-names')
While CommonJS `require` works, ESM `import` is the recommended modern approach. The library supports both.
setEffectiveTags
import { setEffectiveTags } from 'find-test-names'
const { setEffectiveTags } = require('find-test-names')
Used to compute and apply inherited tags throughout the test structure. Available as a named export.
filterByEffectiveTags
import { filterByEffectiveTags } from 'find-test-names'
const filterByEffectiveTags = require('find-test-names').filterByEffectiveTags
This function can accept source code directly or operate on the structure array returned by `getTestNames` after `setEffectiveTags` has been applied.
findEffectiveTestTagsIn
import { findEffectiveTestTagsIn } from 'find-test-names'
require('find-test-names').findEffectiveTestTagsIn('file.js')
This utility directly reads a file from disk and returns effective tags without manual parsing steps.

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.

import { getTestNames, setEffectiveTags, filterByEffectiveTags } from 'find-test-names'; import * as fs from 'node:fs/promises'; async function analyzeSpecFile(filename) { const source = ` describe('Feature A', { tags: '@featureA' }, () => { describe('Sub-feature B', { tags: '@subFeatureB' }, () => { it('should do something important', { tags: ['@smoke', '@critical'] }, () => { // test implementation }); it('should handle edge cases', () => { // another test }); }); it.skip('should be skipped for now', () => {}); }); it('standalone test', { requiredTags: ['@data'] }, () => {}); `; console.log(`Analyzing a mock spec file:\n${source}\n`); // Get the full structure including suite and test names const resultWithStructure = getTestNames(source, true); console.log('Raw structure:', JSON.stringify(resultWithStructure.structure, null, 2)); // Compute effective tags for each test setEffectiveTags(resultWithStructure.structure); console.log('\nStructure with effective tags:', JSON.stringify(resultWithStructure.structure, null, 2)); // Filter tests by a specific effective tag const smokeTests = filterByEffectiveTags(resultWithStructure.structure, ['@smoke']); console.log('\nTests with @smoke tag:', smokeTests.map(t => t.fullTitle)); const allTests = getTestNames(source); console.log('\nSimple list of test names:', allTests.testNames); } analyzeSpecFile('mock.spec.js').catch(console.error);
Debug
Known issues
gotchaThe 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.
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).
affects: >=1.0.0
gotchaWhen 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.
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 }`).
affects: >=1.0.0
gotchaTest 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.
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.
affects: >=1.0.0
breakingVersion 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.
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`.
affects: 1.29.19
Errors
Common errors & fixes
SyntaxError: Unknown word (or similar Babel parsing error)
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.
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.
TypeError: getTestNames is not a function
Attempting to use `getTestNames` as a default export or incorrectly destructuring named exports in CommonJS or ESM environments.
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.
Error: Cannot find module 'find-test-names' or similar module resolution error in an ESM project.
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.
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.
Upgrade
Version history
1.29.19latest on npm
Audit
Dependencies
@babel/parserrequiredCore dependency for parsing JavaScript and TypeScript code to extract test and suite names and their associated metadata.
debugoptionalUsed for internal debugging messages.
tinyglobbyrequiredUsed for globbing file paths, especially when reading files from disk via methods like `findEffectiveTestTagsIn`.
Agent activity
2 hits · last 30 days
node
2
Resources
find-test-names — npm install find-test-names · libregistry