{"record":{"id":"2b9e2d075fe11ab6","repo":"avajs/ava","slug":"the-u2018ava-u2019-module-can-only-be-imported-in","errorCode":null,"errorMessage":"The \\u2018ava\\u2019 module can only be imported in test files","messagePattern":"The \\\\u2018ava\\\\u2019 module can only be imported in test files","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/worker/guard-environment.js","lineNumber":16,"sourceCode":"import path from 'node:path';\nimport process from 'node:process';\n\nimport {isRunningInThread, isRunningInChildProcess} from './utils.js';\n\n// Check if the test is being run without AVA cli\nif (!isRunningInChildProcess && !isRunningInThread) {\n\tif (process.argv[1]) {\n\t\tconst fp = path.relative('.', process.argv[1]);\n\n\t\tconsole.log();\n\t\tconsole.error(`Test files must be run with the AVA CLI:\\n\\n    $ ava ${fp}\\n`);\n\n\t\tprocess.exit(1); // eslint-disable-line unicorn/no-process-exit\n\t} else {\n\t\tthrow new Error('The \\u2018ava\\u2019 module can only be imported in test files');\n\t}\n}\n","sourceCodeStart":1,"sourceCodeEnd":19,"githubUrl":"https://github.com/avajs/ava/blob/bbfd946322fdeca2b547a691d947fb4e18c0c67f/lib/worker/guard-environment.js#L1-L19","documentation":"AVA's test files must be executed by the AVA CLI, which sets up the worker environment (including injectable options). guard-environment.js detects when the 'ava' module is imported outside that environment: if run as a plain node script it prints instructions and exits; otherwise (e.g. imported from non-test code or a different runner) it throws this Error.","triggerScenarios":"Requiring/importing 'ava' from a file run with plain `node file.js`; importing the test file from production code; running test files with another test runner (jest, mocha); importing the test file in a browser or bundler context.","commonSituations":"Running `node test.js` directly instead of `ava`; a tool (coverage, docs generator, bundler) accidentally pulling in a test file; a shared module that imports `ava` and is also used by app code.","solutions":["Run tests with the AVA CLI: `npx ava` or `npm test` configured to use ava.","Extract shared logic out of test files so production code never imports 'ava'.","Exclude test files from bundlers/coverage/other runners so they are never loaded outside AVA."],"exampleFix":"// before (shared.js used by app)\nimport {test} from 'ava';\nexport const helper = ...;\n\n// after (shared.js has no ava import; test file imports both)\n// shared.js\nexport const helper = ...;\n// shared.test.js\nimport test from 'ava';\nimport {helper} from './shared.js';","handlingStrategy":"validation","validationCode":"const isAvaWorker = process.env.NODE_ENV === 'test' && globalThis.__AVA_OPTIONS__ !== undefined; // or check via ava's own guard before importing 'ava'\nif (!isAvaWorker) throw new Error('ava can only be imported inside test files run by the AVA CLI');","typeGuard":"const canImportAva = () => process.argv.some(a => a.includes('ava')) || process.env.AVA_PATH !== undefined;","tryCatchPattern":null,"preventionTips":["Always run test files via the AVA CLI (`npx ava`), never `node test.js`","Keep 'ava' imports out of production/shared modules","Exclude test files from bundlers, coverage tooling, and other test runners"],"tags":["ava","environment","import","misuse"],"backgroundTag":"module-imported-outside-runner","analyzedSha":"bbfd946322fdeca2b547a691d947fb4e18c0c67f","analyzedAt":"2026-09-02T01:24:43.834Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}