From b3d59bdcc57b26d02a4b5eb9f10361b7b90e4a5f Mon Sep 17 00:00:00 2001
From: Caleb Ukle <caleb@nrwl.io>
Date: Mon, 11 Apr 2022 08:51:29 -0500
Subject: [PATCH] docs(core): Add example of using global scripts for jest and
 nx libraries (#9483)

* docs(testing): add example on how to use ts path aliases within jest global setup/teardown

Jest global setup/teardown scripts run before path aliaes are mapped, so the path resigstration must
happen in the userland global scripts that are set to run
initially the thought of doing this within
the jest executor was thought, but this will provide an inconsistent way to running tests if the
tests are run via an editor plugin or calling `jest` directly; therefore, it's deferred to register
the paths within userland files that are needing the paths to be registered in order to allow for
proper handling (cleanup) and not to overcall unneeded features when global scripts are not in use
for those not using the feature.

ISSUES CLOSED: #8709

* cleanup(testing): test the usage of jest global scripts to ensure no regressions

streamline e2e jest project testing and update global tests to test global functions are working as
intended
---
 docs/shared/jest-plugin.md | 17 +++++++++++++++
 e2e/jest/src/jest.test.ts  | 44 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/docs/shared/jest-plugin.md b/docs/shared/jest-plugin.md
index 1af0644bd526d..1e4a8c9717ec0 100644
--- a/docs/shared/jest-plugin.md
+++ b/docs/shared/jest-plugin.md
@@ -118,6 +118,23 @@ By default, coverage reports will be generated in the `coverage/` directory unde
 
 > `coverageDirectory` and `coverageReporters` are configurable via the project configuration file as well.
 
+### Global setup/teardown with nx libraries
+
+In 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.
+Nx provides a helper function that you can import within your setup/teardown file.
+
+```ts
+import { registerTsProject } from 'nx/src/utils/register';
+const cleanupRegisteredPaths = registerTsProject('.', 'tsconfig.base.json');
+
+import { yourFancyFunction } from '@some-org/my-util-library';
+export default async function () {
+  yourFancyFunction();
+}
+// make sure to run the clean up!
+cleanupRegisteredPaths();
+```
+
 ## Debugging Failing Tests
 
 If 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.
diff --git a/e2e/jest/src/jest.test.ts b/e2e/jest/src/jest.test.ts
index ed3674cd0f912..34ac3520830ba 100644
--- a/e2e/jest/src/jest.test.ts
+++ b/e2e/jest/src/jest.test.ts
@@ -8,7 +8,9 @@ import {
 } from '@nrwl/e2e/utils';
 
 describe('Jest', () => {
-  beforeEach(() => newProject());
+  beforeAll(() => {
+    newProject({ name: uniq('proj') });
+  });
 
   it('should be able test projects using jest', async () => {
     const mylib = uniq('mylib');
@@ -23,7 +25,18 @@ describe('Jest', () => {
   it('should merge with jest config globals', async () => {
     const testGlobal = `'My Test Global'`;
     const mylib = uniq('mylib');
+    const utilLib = uniq('util-lib');
     runCLI(`generate @nrwl/workspace:lib ${mylib} --unit-test-runner jest`);
+    runCLI(
+      `generate @nrwl/workspace:lib ${utilLib} --importPath=@global-fun/globals`
+    );
+    updateFile(
+      `libs/${utilLib}/src/index.ts`,
+      stripIndents`
+      export function setup() {console.log('i am a global setup function')}
+      export function teardown() {console.log('i am a global teardown function')}
+    `
+    );
 
     updateFile(`libs/${mylib}/src/lib/${mylib}.ts`, `export class Test { }`);
 
@@ -36,6 +49,31 @@ describe('Jest', () => {
         `
     );
 
+    updateFile(
+      `libs/${mylib}/setup.ts`,
+      stripIndents`
+      const { registerTsProject } = require('nx/src/utils/register');
+      const cleanup = registerTsProject('.', 'tsconfig.base.json');
+      
+      import {setup} from '@global-fun/globals'; 
+      export default async function() {setup();}
+      
+      cleanup();
+    `
+    );
+
+    updateFile(
+      `libs/${mylib}/teardown.ts`,
+      stripIndents`
+      import { registerTsProject } from 'nx/src/utils/register';
+      const cleanup = registerTsProject('.', 'tsconfig.base.json');
+      
+      import {teardown} from '@global-fun/globals'; 
+      export default async function() {teardown();}
+      cleanup();
+    `
+    );
+
     updateFile(
       `libs/${mylib}/jest.config.js`,
       stripIndents`
@@ -48,7 +86,9 @@ describe('Jest', () => {
             moduleFileExtensions: ['ts', 'js', 'html'],
             coverageReporters: ['html'],
             passWithNoTests: true,
-            globals: { testGlobal: ${testGlobal} }
+            globals: { testGlobal: ${testGlobal} },
+            globalSetup: '<rootDir>/setup.ts',
+            globalTeardown: '<rootDir>/teardown.ts'
           };`
     );