nrwl · Coly010 · Feb 28, 2025 · FrozenPandaz · Feb 28, 2025 · Coly010
@@ -117,3 +117,49 @@ Nx uses the paths from `tsconfig.base.json` when running plugins locally, but us
 ## Generator Utilities
 
 The [`@nx/devkit` package](/nx-api/devkit/documents/nx_devkit) provides many utility functions that can be used in generators to help with modifying files, reading and updating configuration files, and working with an Abstract Syntax Tree (AST).
+
+## Unit Testing Generators
+
+Generators will be created with a default test suite. You can add additional tests to this test suite to ensure that your generator is working as expected.
+
+If your generator makes use of or composes generators that make use of Inferred Tasks or Inference Plugins, you will need additional setup in your test suite to ensure that any plugins registered in your current Nx Workspace do not interfere with the unit tests.
+The `@nx/devkit/testing` packages provides a useful utility for this purpose called `TempFs`.
+
+You can use it to create a temporary directory and set it as the current working directory for your tests.
+You should also ensure that you change the process's current working directory to the temporary directory and revert it back to the original directory after your tests have completed.
+
+```typescript {% fileName="my-generator.spec.ts" %}
+import { createTreeWithEmptyWorkspace, TempFs } from '@nx/devkit/testing';
+import { myGeneratorGenerator } from './my-generator';
+
+describe('my-generator generator', () => {
+  let tree: Tree;
+  let tempFs: TempFs;
+
+  // Note that original cwd is stored to be restored after the test
+  const cwd = process.cwd();
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+    tempFs = new TempFs('test');
+    tempFs.createFileSync('nx.json', `{}`);
+    tree.write('nx.json', `{}`);
+    // Note that tree's root is set to the temp directory
+    tree.root = tempFs.tempDir;
+    // Note that process.cwd() is set to the temp directory
+    process.chdir(tree.root);
+  });
+
+  afterEach(() => {
+    tempFs.reset();
+    // Note that process.cwd() is restored to the original directory
+    process.chdir(cwd);
+  });
+
+  // Replace with your test cases
+  it('should run the generator', async () => {
+    await myGeneratorGenerator(tree, { ...opts });
+    expect(true).toBe(true);
+  });
+});
+```
@@ -1,6 +1,6 @@
 import type { CreateNodesContextV2 } from '@nx/devkit';
 import { mkdirSync, rmdirSync } from 'node:fs';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { createNodesV2, type AngularProjectConfiguration } from './plugin';
 
 jest.mock('nx/src/utils/cache-directory', () => ({

@@ -16,7 +16,7 @@ import {
   updateNxJson,
   writeJson,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { join } from 'node:path';
 
 let fs: TempFs;

@@ -1,6 +1,6 @@
 import { ProjectGraph, readNxJson, type Tree, updateNxJson } from '@nx/devkit';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import addE2eCiTargetDefaults from './add-e2e-ci-target-defaults';
 
 let projectGraph: ProjectGraph;

@@ -6,7 +6,7 @@ import {
   updateNxJson,
 } from '@nx/devkit';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 
 let projectGraph: ProjectGraph;
 jest.mock('@nx/devkit', () => ({

@@ -2,7 +2,7 @@ import { CreateNodesContext } from '@nx/devkit';
 import { defineConfig } from 'cypress';
 
 import { createNodesV2 } from './plugin';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { resetWorkspaceContext } from 'nx/src/utils/workspace-context';
 import { join } from 'path';
 import { nxE2EPreset } from '../../plugins/cypress-preset';

@@ -8,7 +8,7 @@ import {
   type Tree,
   writeJson,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import { join } from 'node:path';
 import { getRelativeProjectJsonSchemaPath } from 'nx/src/generators/utils/project-configuration';

@@ -2,5 +2,4 @@
 export * from 'nx/src/internal-testing-utils/assert-valid-migrations';
 export * from 'nx/src/internal-testing-utils/run-migration-against-this-workspace';
 export * from 'nx/src/internal-testing-utils/with-environment';
-export * from 'nx/src/internal-testing-utils/temp-fs';
 export { setCwd } from './src/generators/artifact-name-and-directory-utils';
@@ -1,6 +1,6 @@
 import { createTreeWithEmptyWorkspace } from 'nx/src/devkit-testing-exports';
 import { type Tree, readNxJson, updateNxJson } from 'nx/src/devkit-exports';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from 'nx/src/generators/testing-utils/temp-fs';
 import { getE2EWebServerInfo } from './e2e-web-server-info-utils';
 
 describe('getE2EWebServerInfo', () => {

@@ -1,7 +1,8 @@
 import { createTreeWithEmptyWorkspace } from 'nx/src/devkit-testing-exports';
 import { readNxJson, updateNxJson, type Tree } from 'nx/src/devkit-exports';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from 'nx/src/generators/testing-utils/temp-fs';
 import { addE2eCiTargetDefaults } from './target-defaults-utils';
+
 describe('target-defaults-utils', () => {
   describe('addE2eCiTargetDefaults', () => {
     let tree: Tree;

@@ -4,7 +4,7 @@ import { readJson, writeJson } from 'nx/src/generators/utils/json';
 import type { PackageJson } from 'nx/src/utils/package-json';
 import { CreateNodesV2 } from 'nx/src/project-graph/plugins';
 import { ProjectGraph } from 'nx/src/devkit-exports';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from 'nx/src/generators/testing-utils/temp-fs';
 
 import { addPlugin, generateCombinations } from './add-plugin';
 

@@ -1,4 +1,4 @@
-import { TempFs } from '../../internal-testing-utils';
+import { TempFs } from '../../testing';
 import { convertNxExecutor } from './convert-nx-executor';
 
 describe('Convert Nx Executor', () => {

@@ -1,5 +1,5 @@
 import { type Tree, readNxJson, updateNxJson } from 'nx/src/devkit-exports';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from 'nx/src/generators/testing-utils/temp-fs';
 import { createTreeWithEmptyWorkspace } from 'nx/src/devkit-testing-exports';
 import { findPluginForConfigFile } from './find-plugin-for-config-file';
 

@@ -1,5 +1,5 @@
 import type { ExecutorContext } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import * as fs from 'fs';
 import { resolve } from 'path';
 import type { Schema } from './schema';
@@ -24,6 +24,7 @@ class MockESLint {
   loadFormatter = mockLoadFormatter;
   isPathIgnored = mockIsPathIgnored;
   lintFiles = mockLintFiles;
+
   calculateConfigForFile(file: string) {
     return { file: file };
   }

@@ -11,7 +11,7 @@ import {
   type ProjectGraph,
   type Tree,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import { join } from 'node:path';
 import {

@@ -1,5 +1,5 @@
 import { readJson, writeJson, type Tree } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import migration from './update-typescript-eslint-v8-13-0';
 

@@ -1,6 +1,6 @@
 import { CreateNodesContextV2 } from '@nx/devkit';
 import { minimatch } from 'minimatch';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { createNodesV2, EslintPluginOptions } from './plugin';
 import { mkdirSync, rmdirSync } from 'fs';
 

@@ -1,4 +1,4 @@
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { join } from 'path';
 import {
   ESLINT_FLAT_CONFIG_FILENAMES,

@@ -9,7 +9,7 @@ import {
   type Tree,
   writeJson,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import { join } from 'node:path';
 import { getRelativeProjectJsonSchemaPath } from 'nx/src/generators/utils/project-configuration';

@@ -1,5 +1,5 @@
 import { CreateNodesContext } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createNodesV2 } from './plugin';
 import { type GradleReport } from './src/utils/get-gradle-report';
 

@@ -1,6 +1,6 @@
 import { CreateNodesContext } from '@nx/devkit';
 
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { type GradleReport } from '../utils/get-gradle-report';
 
 let gradleReport: GradleReport;

@@ -1,4 +1,4 @@
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { findGraldewFile } from './exec-gradle';
 
 describe('exec gradle', () => {

@@ -1,4 +1,4 @@
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { splitConfigFiles } from './split-config-files';
 
 describe('split config files', () => {

@@ -10,7 +10,7 @@ import {
   type ProjectGraph,
   type Tree,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import { join } from 'node:path';
 import {

@@ -1,5 +1,5 @@
 import { CreateNodesContext } from '@nx/devkit';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { join } from 'path';
 import { createNodesV2 } from './plugin';
 

@@ -1,5 +1,5 @@
 import { detectPackageManager, type CreateNodesContext } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import picomatch = require('picomatch');
 import { mkdirSync, rmdirSync } from 'node:fs';
 // eslint-disable-next-line @typescript-eslint/no-restricted-imports

@@ -1,5 +1,5 @@
 import { DependencyType, ProjectGraph, TaskGraph } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { readFileSync } from 'fs';
 import {
   calculateDependenciesFromTaskGraph,

@@ -1,5 +1,5 @@
 import { ExecException } from 'child_process';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 import { PackageJson } from 'nx/src/utils/package-json';
 import { join } from 'path';
 import { getNpmRegistry, getNpmTag, parseRegistryOptions } from './npm-config';

@@ -9,7 +9,7 @@ import {
   type Tree,
   writeJson,
 } from '@nx/devkit';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
 import { join } from 'node:path';
 import { getRelativeProjectJsonSchemaPath } from 'nx/src/generators/utils/project-configuration';

@@ -2,7 +2,7 @@ import { CreateNodesContext } from '@nx/devkit';
 import type { NextConfig } from 'next';
 
 import { createNodesV2 } from './plugin';
-import { TempFs } from '@nx/devkit/internal-testing-utils';
+import { TempFs } from '@nx/devkit/testing';
 
 describe('@nx/next/plugin', () => {
   let createNodesFunction = createNodesV2[1];

@@ -1,6 +1,6 @@
 import { CreateNodesContext } from '@nx/devkit';
 import { createNodes } from './plugin';
-import { TempFs } from 'nx/src/internal-testing-utils/temp-fs';
+import { TempFs } from '@nx/devkit/testing';
 
 jest.mock('@nx/devkit/src/utils/config-utils', () => ({
   loadConfigFile: jest.fn().mockImplementation(() => {

@@ -1,6 +1,6 @@
 import { join } from 'path';
 import { ProjectFileMap, ProjectGraph } from '../../../config/project-graph';
-import { TempFs } from '../../../internal-testing-utils/temp-fs';
+import { TempFs } from '../../../generators/testing-utils/temp-fs';
 import { createNxReleaseConfig } from './config';
 
 expect.addSnapshotSerializer({

@@ -1,6 +1,6 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
-import { TempFs } from '../../../internal-testing-utils/temp-fs';
+import { TempFs } from '../../../generators/testing-utils/temp-fs';
 import { IMPLICIT_DEFAULT_RELEASE_GROUP } from './config';
 import { ReleaseGroupWithName } from './filter-release-groups';
 import {
@@ -1150,6 +1150,7 @@ describe('version-plans', () => {
   });
 
   let createdOnAccumulator = 1;
+
   function versionPlan({
     name,
     content,

@@ -1,5 +1,5 @@
 import { toProjectName } from './to-project-name';
-import { TempFs } from '../internal-testing-utils/temp-fs';
+import { TempFs } from '../generators/testing-utils/temp-fs';
 import { withEnvironmentVariables } from '../internal-testing-utils/with-environment';
 import { retrieveProjectConfigurations } from '../project-graph/utils/retrieve-workspace-files';
 import { readNxJson } from './configuration';

@@ -3,3 +3,4 @@ export {
   createTreeWithEmptyV1Workspace,
 } from './generators/testing-utils/create-tree-with-empty-workspace';
 export { createTree } from './generators/testing-utils/create-tree';
+export { TempFs } from './generators/testing-utils/temp-fs';