{"id":15328,"library":"find-test-names-tags","title":"Mocha/Cypress Test Name and Tag Extractor","description":"The `find-test-names-tags` package, currently at stable version 1.0.4, is a utility designed for parsing JavaScript test files, specifically those written for Mocha and Cypress frameworks. Its primary function is to extract comprehensive information about test suites and individual test cases, including their names and any associated tags. A significant feature is its ability to compute \"effective tags\" for each test, which involves aggregating tags from the test itself and its parent suites. This allows for powerful filtering capabilities, enabling users to isolate tests based on specific tags or combinations thereof. The package also provides command-line interfaces for printing structured test outlines, including marking pending tests and displaying their tags. While a precise release cadence isn't specified, the package appears to be actively maintained and developed. It stands out by offering fine-grained control over test metadata extraction and analysis, making it valuable for dynamic test reporting, selective test execution in CI/CD pipelines, or building custom test dashboards. It effectively bridges the gap between raw test code and actionable test metadata.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/ManuelBuslon/find-test-names","tags":["javascript","mocha","cypress","tests"],"install":[{"cmd":"npm install find-test-names-tags","lang":"bash","label":"npm"},{"cmd":"yarn add find-test-names-tags","lang":"bash","label":"yarn"},{"cmd":"pnpm add find-test-names-tags","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package primarily uses CommonJS `require` syntax as shown in documentation.","wrong":"import { getTestNames } from 'find-test-names-tags'","symbol":"getTestNames","correct":"const { getTestNames } = require('find-test-names-tags')"},{"note":"A named export function to compute and set effective tags on a parsed test structure.","wrong":"import { setEffectiveTags } from 'find-test-names-tags'","symbol":"setEffectiveTags","correct":"const { setEffectiveTags } = require('find-test-names-tags')"},{"note":"This function can accept either the parsed structure or the raw source code directly for convenience.","wrong":"import { filterByEffectiveTags } from 'find-test-names-tags'","symbol":"filterByEffectiveTags","correct":"const { filterByEffectiveTags } = require('find-test-names-tags')"}],"quickstart":{"code":"const specSourceCode = `\ndescribe(['@user'], 'User Features', () => {\n  describe(['@auth'], 'Authentication', () => {\n    it(['@smoke'], 'should allow login', () => {\n      // test implementation\n    });\n    it(['@regression', '@critical'], 'should handle failed login attempts', () => {\n      // test implementation\n    });\n  });\n  describe('Profile', () => {\n    const dynamicName = 'should update profile';\n    it(dynamicName, () => {\n      // test implementation\n    });\n  });\n});\n`;\n\nconst { getTestNames, setEffectiveTags, filterByEffectiveTags } = require('find-test-names-tags');\n\n// Get the full test structure (important: pass true for structure)\nconst result = getTestNames(specSourceCode, true);\nconsole.log('Parsed structure root keys:', Object.keys(result));\n\n// Compute effective tags for each test within the structure\nsetEffectiveTags(result.structure);\nconsole.log('Effective tags for \"should allow login\":', result.structure[0].suites[0].tests[0].effectiveTags);\n\n// Filter tests by effective tags (e.g., find all smoke tests)\nconst smokeTests = filterByEffectiveTags(result.structure, ['@smoke'], []);\nconsole.log('Found smoke tests:', smokeTests.map(t => t.name));\n\n// Filter by multiple tags, excluding others (e.g., regression but not critical)\nconst regressionExcludingCritical = filterByEffectiveTags(specSourceCode, ['@regression'], ['@critical']);\nconsole.log('Regression tests (excluding critical):', regressionExcludingCritical.map(t => t.name));","lang":"javascript","description":"Demonstrates parsing a mock spec file, retrieving the full test structure, computing effective tags for tests, and then filtering these tests based on specific tag criteria."},"warnings":[{"fix":"This is expected behavior and not an error. If exact variable-defined names are critical, ensure test names are always literal strings where possible.","message":"When `getTestNames` encounters test names defined by variables instead of literal strings, it will extract and process them, but the name in the output will be reported as `<unknown test>`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always call `getTestNames(sourceCode, true)` when you intend to work with the full `result.structure` for advanced tag processing.","message":"To utilize functions like `setEffectiveTags` and access the nested test structure, you *must* pass `true` as the second argument to `getTestNames`. Omitting this argument returns a flat list of names, lacking the hierarchical structure required for tag propagation.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you call `const result = getTestNames(specSourceCode, true)` to correctly populate the `structure` property.","cause":"This error typically occurs when trying to access `result.structure` after calling `getTestNames()` without the `true` argument, which means the `structure` property was not populated.","error":"TypeError: Cannot read properties of undefined (reading 'structure')"},{"fix":"Use the CommonJS destructuring assignment: `const { getTestNames } = require('find-test-names-tags')`.","cause":"This indicates an incorrect import statement. The package primarily uses CommonJS named exports, and attempting to use an ESM `import` or an incorrect `require` pattern will lead to this error.","error":"TypeError: getTestNames is not a function"}],"ecosystem":"npm"}