jest.json

{
  "githubRoot": "https://github.com/nrwl/nx/blob/master",
  "name": "jest",
  "packageName": "@nrwl/jest",
  "description": "The Nx Plugin for Jest contains executors and generators allowing your workspace to use the powerful Jest testing capabilities.",
  "root": "/packages/jest",
  "source": "/packages/jest/src",
  "documentation": [
    {
      "name": "Overview",
      "id": "overview",
      "path": "/packages/jest",
      "file": "shared/jest-plugin",
      "content": "[Jest](https://jestjs.io/) is an open source test runner created by Facebook. It has a lot of great features:\n\n- Immersive watch mode for providing near instant feedback when developing tests.\n- Snapshot testing for validating features.\n- Great built-in reporter for printing out test results.\n\n## Setting up Jest\n\nBy default, Nx will use Jest when creating applications and libraries.\n\n```shell\nnx g @nrwl/web:app frontend\n```\n\n### Adding Jest to an Existing Project\n\nAdd Jest to a project using the `jest-project` generator from `@nrwl/jest`.\n\nFirst, install `@nrwl/jest`, if not already installed using your preferred package manager.\n\n```shell\nnpm install --save-dev @nrwl/jest\n```\n\n```shell\nyarn add --dev @nrwl/jest\n```\n\nOnce installed, run the `jest-project` generator\n\n```shell\nnx g @nrwl/jest:jest-project --project=<project-name>\n```\n\n> Hint: You can use the `--dry-run` flag to see what will be generated.\n\nReplacing `<project-name>` with the name of the project you're wanting to add Jest too.\n\n## Using Jest\n\n### Testing Applications\n\nThe recommended way to run/debug Jest tests via an editor\n\n- [VSCode](https://marketplace.visualstudio.com/items?itemName=firsttris.vscode-jest-runner)\n- [Webstorm](https://blog.jetbrains.com/webstorm/2018/10/testing-with-jest-in-webstorm/)\n\nTo run Jest tests via nx use\n\n```shell\nnx test frontend\n```\n\n### Watching for Changes\n\nUsing the `--watch` flag will run the tests whenever a file changes.\n\n```shell\nnx test frontend --watch\n```\n\n### Snapshot Testing\n\nJest has support for **Snapshot Testing**, a tool which simplifies validating data. Check out the [official Jest Documentation on Snapshot Testing](https://jestjs.io/docs/en/snapshot-testing).\n\nExample of using snapshots:\n\n```typescript\ndescribe('SuperAwesomFunction', () => {\n  it('should return the correct data shape', () => {\n    const actual = superAwesomFunction();\n    expect(actual).toMatchSnapshot();\n  });\n});\n```\n\nWhen using snapshots, you can update them with the `--updateSnapshot` flag, `-u` for short.\n\n> By default, snapshots will be generated when there are not existing snapshots for the associated test.\n\n```shell\nnx test frontend -u\n```\n\nSnapshot files should be checked in with your code.\n\n### Performance in CI\n\nTypically, in CI it's recommended to use `nx affected --target=test --parallel=[# CPUs] -- --runInBand` for the best performance.\n\nThis is because each [jest process creates a workers based on system resources](https://jestjs.io/docs/cli#--maxworkersnumstring), running multiple projects via nx and using jest workers will create too many process overall causing the system to run slower than desired. Using the `--runInBand` flag tells jest to run in a single process.\n\n## Configurations\n\n### Jest\n\nPrimary configurations for Jest will be via the `jest.config.js` file that generated for your project. This file will extend the root `jest.config.js` file. Learn more about [Jest configurations](https://jestjs.io/docs/configuration#options).\n\n### Nx\n\nNx Jest Plugin options can be configured via the [project config file](/reference/project-configuration) or via the [command line flags](/packages/jest).\n\n> Hint: Use `--help` to see all available options\n>\n> ```shell\n> nx test <project-name> --help\n> ```\n\n### Code Coverage\n\nEnable code coverage with the `--coverage` flag or by adding it to the executor options in the [project configuration file](/reference/project-configuration).\n\nBy default, coverage reports will be generated in the `coverage/` directory under projects name. i.e. `coverage/apps/frontend`. Modify this directory with the `--coverageDirectory` flag. Coverage reporters can also be customized with the `--coverageReporters` flag.\n\n> `coverageDirectory` and `coverageReporters` are configurable via the project configuration file as well.\n\n### Global setup/teardown with nx libraries\n\nIn order to use Jest's global setup/teardown functions that reference nx libraries, you'll need to register the TS path for jest to resolve the libraries.\nNx provides a helper function that you can import within your setup/teardown file.\n\n```typescript\nimport { registerTsProject } from 'nx/src/utils/register';\nconst cleanupRegisteredPaths = registerTsProject('.', 'tsconfig.base.json');\n\nimport { yourFancyFunction } from '@some-org/my-util-library';\nexport default async function () {\n  yourFancyFunction();\n}\n// make sure to run the clean up!\ncleanupRegisteredPaths();\n```\n\n## Debugging Failing Tests\n\nIf your code editor doesn't provide a way to debug your tests, you can leverage the Chrome DevTools to debug your tests with the `--inspect-brk` flag for node.\n\n```shell\nnode --inspect-brk ./node_modules/@nrwl/cli/bin/nx test <project-name>\n```\n\nEnter [chrome://inspect](chrome://inspect) in Chrome address bar and inspect the target to attach to the node process. Visit the official [Jest documentation](https://jestjs.io/docs/en/troubleshooting#tests-are-failing-and-you-don-t-know-why) to find out more.\n\n## More Documentation\n\n- [Jest Docs](https://jestjs.io/)\n- [@nrwl/jest options](/packages/jest)\n"
    }
  ],
  "generators": [
    {
      "name": "init",
      "factory": "./src/generators/init/init#jestInitGenerator",
      "schema": {
        "$schema": "http://json-schema.org/schema",
        "$id": "NxJestInit",
        "cli": "nx",
        "title": "Jest init",
        "description": "Add Jest Configuration to a workspace.",
        "type": "object",
        "properties": {
          "babelJest": {
            "type": "boolean",
            "alias": "babel-jest",
            "description": "Use `babel-jest` instead of `ts-jest`.",
            "default": false
          },
          "skipPackageJson": {
            "type": "boolean",
            "default": false,
            "description": "Do not add dependencies to `package.json`."
          },
          "js": {
            "type": "boolean",
            "default": false,
            "description": "Use JavaScript instead of TypeScript for config files"
          }
        },
        "required": [],
        "presets": []
      },
      "description": "Initialize the `@nrwl/jest` plugin.",
      "aliases": ["ng-add"],
      "hidden": true,
      "implementation": "/packages/jest/src/generators/init/init#jestInitGenerator.ts",
      "path": "/packages/jest/src/generators/init/schema.json"
    },
    {
      "name": "jest-project",
      "factory": "./src/generators/jest-project/jest-project#jestProjectGenerator",
      "schema": {
        "$schema": "http://json-schema.org/schema",
        "$id": "NxJestProject",
        "cli": "nx",
        "title": "Add Jest Configuration to a project",
        "description": "Add Jest Configuration to a project.",
        "type": "object",
        "properties": {
          "project": {
            "type": "string",
            "description": "The name of the project.",
            "$default": { "$source": "projectName" }
          },
          "skipSetupFile": {
            "type": "boolean",
            "description": "[Deprecated]: Skips the setup file required for angular. (Use `--setup-file`)",
            "default": false,
            "x-deprecated": true
          },
          "setupFile": {
            "type": "string",
            "enum": ["none", "angular", "web-components"],
            "description": "The setup file to be generated.",
            "default": "none"
          },
          "skipSerializers": {
            "type": "boolean",
            "description": "Skips the serializers required to snapshot angular templates.",
            "default": false
          },
          "supportTsx": {
            "type": "boolean",
            "description": "Setup `tsx` support.",
            "default": false
          },
          "testEnvironment": {
            "type": "string",
            "enum": ["jsdom", "node"],
            "description": "The test environment for jest.",
            "default": "jsdom"
          },
          "compiler": {
            "type": "string",
            "enum": ["tsc", "babel", "swc"],
            "description": "The compiler to use for source and tests.",
            "default": "tsc"
          },
          "babelJest": {
            "type": "boolean",
            "alias": "babel-jest",
            "description": "Use `babel-jest` instead of `ts-jest` (Deprecated: Use `--compiler=babel` instead).",
            "x-deprecated": true,
            "default": false
          },
          "skipFormat": {
            "description": "Skip formatting files",
            "type": "boolean",
            "default": false
          },
          "skipPackageJson": {
            "type": "boolean",
            "default": false,
            "description": "Do not add dependencies to `package.json`."
          },
          "js": {
            "type": "boolean",
            "default": false,
            "description": "Use JavaScript instead of TypeScript for config files"
          }
        },
        "required": [],
        "presets": []
      },
      "description": "Add Jest configuration to a project.",
      "hidden": true,
      "implementation": "/packages/jest/src/generators/jest-project/jest-project#jestProjectGenerator.ts",
      "aliases": [],
      "path": "/packages/jest/src/generators/jest-project/schema.json"
    }
  ],
  "executors": [
    {
      "name": "jest",
      "implementation": "/packages/jest/src/executors/jest/jest.impl.ts",
      "batchImplementation": "./src/executors/jest/jest.impl#batchJest",
      "schema": {
        "version": 2,
        "outputCapture": "direct-nodejs",
        "title": "Jest Builder",
        "description": "Jest target options for Build Facade.",
        "cli": "nx",
        "type": "object",
        "presets": [
          {
            "name": "Pass Without Tests",
            "keys": ["jestConfig", "passWithNoTests"]
          },
          {
            "name": "Code Coverage",
            "keys": ["jestConfig", "coverageReporters"]
          },
          { "name": "Stop After 'n' Failed", "keys": ["jestConfig", "bail"] }
        ],
        "properties": {
          "codeCoverage": {
            "description": "Indicates that test coverage information should be collected and reported in the output. (https://jestjs.io/docs/cli#--coverageboolean)",
            "type": "boolean",
            "aliases": ["coverage"]
          },
          "config": {
            "description": "The path to a Jest config file specifying how to find and execute tests. If no `rootDir` is set in the config, the directory containing the config file is assumed to be the `rootDir` for the project. This can also be a JSON-encoded value which Jest will use as configuration.",
            "type": "string"
          },
          "clearCache": {
            "description": "Deletes the Jest cache directory and then exits without running tests. Will delete Jest's default cache directory. _Note: clearing the cache will reduce performance_.",
            "type": "boolean"
          },
          "detectOpenHandles": {
            "description": "Attempt to collect and print open handles preventing Jest from exiting cleanly (https://jestjs.io/docs/cli#--detectopenhandles)",
            "type": "boolean"
          },
          "logHeapUsage": {
            "description": "Logs the heap usage after every test. Useful to debug memory leaks. Use together with --runInBand and --expose-gc in node.",
            "type": "boolean"
          },
          "detectLeaks": {
            "description": "**EXPERIMENTAL**: Detect memory leaks in tests. After executing a test, it will try to garbage collect the global object used, and fail if it was leaked",
            "type": "boolean"
          },
          "jestConfig": {
            "description": "The path of the Jest configuration. (https://jestjs.io/docs/en/configuration)",
            "type": "string",
            "x-completion-type": "file",
            "x-completion-glob": "jest.config@(.js|.ts)"
          },
          "testFile": {
            "description": "The name of the file to test.",
            "type": "string"
          },
          "tsConfig": {
            "description": "The name of the Typescript configuration file. Set the tsconfig option in the jest config file. ",
            "type": "string",
            "x-deprecated": true
          },
          "setupFile": {
            "description": "The name of a setup file used by Jest. (use Jest config file https://jestjs.io/docs/en/configuration#setupfilesafterenv-array)",
            "type": "string",
            "x-deprecated": true
          },
          "bail": {
            "alias": "b",
            "description": "Exit the test suite immediately after `n` number of failing tests. (https://jestjs.io/docs/cli#--bail)",
            "oneOf": [{ "type": "number" }, { "type": "boolean" }]
          },
          "ci": {
            "description": "Whether to run Jest in continuous integration (CI) mode. This option is on by default in most popular CI environments. It will prevent snapshots from being written unless explicitly requested. (https://jestjs.io/docs/cli#--ci)",
            "type": "boolean"
          },
          "color": {
            "alias": "colors",
            "description": "Forces test results output color highlighting (even if `stdout` is not a TTY). Set to false if you would like to have no colors. (https://jestjs.io/docs/cli#--colors)",
            "type": "boolean"
          },
          "findRelatedTests": {
            "description": "Find and run the tests that cover a comma separated list of source files that were passed in as arguments. (https://jestjs.io/docs/cli#--findrelatedtests-spaceseparatedlistofsourcefiles)",
            "type": "string"
          },
          "json": {
            "description": "Prints the test results in `JSON`. This mode will send all other test output and user messages to `stderr`. (https://jestjs.io/docs/cli#--json)",
            "type": "boolean"
          },
          "maxWorkers": {
            "alias": "w",
            "description": "Specifies the maximum number of workers the worker-pool will spawn for running tests. This defaults to the number of the cores available on your machine. Useful for CI. (its usually best not to override this default) (https://jestjs.io/docs/cli#--maxworkersnumstring)",
            "oneOf": [{ "type": "number" }, { "type": "string" }]
          },
          "onlyChanged": {
            "alias": "o",
            "description": "Attempts to identify which tests to run based on which files have changed in the current repository. Only works if you're running tests in a `git` or `hg` repository at the moment. (https://jestjs.io/docs/cli#--onlychanged)",
            "type": "boolean"
          },
          "changedSince": {
            "description": "Runs tests related to the changes since the provided branch or commit hash. If the current branch has diverged from the given branch, then only changes made locally will be tested. (https://jestjs.io/docs/cli#--changedsince)",
            "type": "string"
          },
          "outputFile": {
            "description": "Write test results to a file when the `--json` option is also specified. (https://jestjs.io/docs/cli#--outputfilefilename)",
            "type": "string"
          },
          "passWithNoTests": {
            "description": "Will not fail if no tests are found (for example while using `--testPathPattern`.) (https://jestjs.io/docs/cli#--passwithnotests)",
            "type": "boolean"
          },
          "runInBand": {
            "alias": "i",
            "description": "Run all tests serially in the current process (rather than creating a worker pool of child processes that run tests). This is sometimes useful for debugging, but such use cases are pretty rare. Useful for CI. (https://jestjs.io/docs/cli#--runinband)",
            "type": "boolean"
          },
          "showConfig": {
            "description": "Print your Jest config and then exits. (https://jestjs.io/docs/en/cli#--showconfig)",
            "type": "boolean"
          },
          "silent": {
            "description": "Prevent tests from printing messages through the console. (https://jestjs.io/docs/cli#--silent)",
            "type": "boolean"
          },
          "testNamePattern": {
            "alias": "t",
            "description": "Run only tests with a name that matches the regex pattern. (https://jestjs.io/docs/cli#--testnamepatternregex)",
            "type": "string"
          },
          "testPathIgnorePatterns": {
            "description": "An array of regexp pattern strings that is matched against all tests paths before executing the test. Only run those tests with a path that does not match with the provided regexp expressions. (https://jestjs.io/docs/cli#--testpathignorepatternsregexarray)",
            "type": "array",
            "items": { "type": "string" }
          },
          "testPathPattern": {
            "description": "An array of regexp pattern strings that is matched against all tests paths before executing the test. (https://jestjs.io/docs/cli#--testpathpatternregex)",
            "type": "array",
            "items": { "type": "string" },
            "default": []
          },
          "colors": {
            "description": "Forces test results output highlighting even if stdout is not a TTY. (https://jestjs.io/docs/cli#--colors)",
            "type": "boolean"
          },
          "reporters": {
            "description": "Run tests with specified reporters. Reporter options are not available via CLI. Example with multiple reporters: `jest --reporters=\"default\" --reporters=\"jest-junit\"`. (https://jestjs.io/docs/cli#--reporters)",
            "type": "array",
            "items": { "type": "string" }
          },
          "verbose": {
            "description": "Display individual test results with the test suite hierarchy. (https://jestjs.io/docs/cli#--verbose)",
            "type": "boolean"
          },
          "coverageReporters": {
            "description": "A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter.",
            "type": "array",
            "items": { "type": "string" }
          },
          "coverageDirectory": {
            "description": "The directory where Jest should output its coverage files.",
            "type": "string",
            "x-completion-type": "directory"
          },
          "testResultsProcessor": {
            "description": "Node module that implements a custom results processor. (https://jestjs.io/docs/en/configuration#testresultsprocessor-string)",
            "type": "string"
          },
          "updateSnapshot": {
            "alias": "u",
            "description": "Use this flag to re-record snapshots. Can be used together with a test suite pattern or with `--testNamePattern` to re-record snapshot for test matching the pattern. (https://jestjs.io/docs/cli#--updatesnapshot)",
            "type": "boolean"
          },
          "useStderr": {
            "description": "Divert all output to stderr.",
            "type": "boolean"
          },
          "watch": {
            "description": "Watch files for changes and rerun tests related to changed files. If you want to re-run all tests when a file has changed, use the `--watchAll` option. (https://jestjs.io/docs/cli#--watch)",
            "type": "boolean"
          },
          "watchAll": {
            "description": "Watch files for changes and rerun all tests when something changes. If you want to re-run only the tests that depend on the changed files, use the `--watch` option. (https://jestjs.io/docs/cli#--watchall)",
            "type": "boolean"
          },
          "testLocationInResults": {
            "description": "Adds a location field to test results.  Used to report location of a test in a reporter. { \"column\": 4, \"line\": 5 } (https://jestjs.io/docs/cli#--testlocationinresults)",
            "type": "boolean"
          },
          "testTimeout": {
            "description": "Default timeout of a test in milliseconds. Default value: `5000`. (https://jestjs.io/docs/cli#--testtimeoutnumber)",
            "type": "number"
          }
        },
        "required": ["jestConfig"],
        "examplesFile": "Jest can be configured in many ways, but primarily you'll need to at least have the jestConfig options\n\n```json\n\"test\": {\n  \"executor\": \"@nrwl/jest:jest\",\n  \"options\": {\n    \"jestConfig\": \"libs/my-lib/jest.config.ts\"\n  }\n}\n```\n\nIt is also helpful to have `passWithNoTests: true` set so your project doesn't fail testing while tests are still being added.\n\n```json\n\"test\": {\n  \"executor\": \"@nrwl/jest:jest\",\n  \"options\": {\n    \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n    \"passWithNoTests\": true\n  }\n}\n```\n\n### Snapshots\n\nUpdate snapshots running with `--update-snapshot` or `-u` for short.\n\n```bash\nnx test my-project -u\n```\n\nOther times you might not want to allow updating snapshots such as in CI.\nAdding a _ci_ configuration is helpful for adding this behavior.\n\n```json\n\"test\": {\n  \"executor\": \"@nrwl/jest:jest\",\n  \"options\": {\n    \"jestConfig\": \"libs/my-lib/jest.config.ts\",\n    \"passWithNoTests\": true\n  },\n  \"configurations\": {\n    \"ci\": {\n      \"ci\": true\n    }\n  }\n}\n```\n\n```bash\nnx affected --target=test --configuration=ci\n```\n\nLearn more [about _affected_](/concepts/affected)\n"
      },
      "description": "Run Jest unit tests.",
      "aliases": [],
      "hidden": false,
      "path": "/packages/jest/src/executors/jest/schema.json"
    }
  ]
}