fix(core): temp cleanup does not work with jest (#36226)

Our temporary cleanup fix submitted in #36043 doesn't work for tests run with `jest`, because `jest` suppresses the standard Node `exit` event, causing the cleanup to never run.

Instead, we introduce a new public static function which people using `jest` can call:

```ts
afterAll(CloudAssembly.cleanupTemporaryDirectories);
```

As well as a convenience script to automatically inject this handler into all jest tests:

```
$ jest --setupFilesAfterEnv aws-cdk-lib/testhelpers/jest-autoclean
```

Once this PR has been merged and released we will add the above to all CLI init templates.

Closes #802, hopefully for good.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: rix0rrr

packages/aws-cdk-lib/cx-api/lib/cloud-assembly.ts

@@ -33,6 +33,53 @@ export class CloudAssembly implements ICloudAssembly {
     return x !== null && typeof(x) === 'object' && CLOUD_ASSEMBLY_SYMBOL in x;
   }
 
+  /**
+   * Cleans up any temporary assembly directories that got created in this process
+   *
+   * If a Cloud Assembly is emitted to a temporary directory, its directory gets
+   * added to a list. This function iterates over that list and deletes each
+   * directory in it, to free up disk space.
+   *
+   * This function will normally be called automatically during Node process
+   * exit and so you don't need to call this. However, some test environments do
+   * not properly trigger Node's `exit` event. Notably: Jest does not trigger
+   * the `exit` event (<https://github.com/jestjs/jest/issues/10927>).
+   *
+   * ## Cleaning up temporary directories in jest
+   *
+   * For Jest, you have to make sure this function is called at the end of the
+   * test suite instead:
+   *
+   * ```js
+   * import { CloudAssembly } from 'aws-cdk-lib/cx-api';
+   *
+   * afterAll(CloudAssembly.cleanupTemporaryDirectories);
+   * ```
+   *
+   * Alternatively, you can use the `setupFilesAfterEnv` feature and use a
+   * provided helper script to automatically inject the above into every
+   * test file, so you don't have to do it by hand.
+   *
+   * ```
+   * $ npx jest --setupFilesAfterEnv aws-cdk-lib/testhelpers/jest-autoclean
+   * ```
+   *
+   * Or put the following into `jest.config.js`:
+   *
+   * ```js
+   * module.exports = {
+   *   // ...
+   *   setupFilesAfterEnv: ['aws-cdk-lib/testhelpers/jest-cleanup'],
+   * };
+   * ```
+   */
+  public static cleanupTemporaryDirectories() {
+    for (const dir of TEMPORARY_ASSEMBLY_DIRS) {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+    TEMPORARY_ASSEMBLY_DIRS.splice(0, TEMPORARY_ASSEMBLY_DIRS.length);
+  }
+
   /**
    * The root directory of the cloud assembly.
    */
@@ -498,8 +545,4 @@ function ensureDirSync(dir: string) {
 
 // On process exit, delete all temporary assembly directories
 const TEMPORARY_ASSEMBLY_DIRS: string[] = [];
-process.on('exit', () => {
-  for (const dir of TEMPORARY_ASSEMBLY_DIRS) {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-});
+process.on('exit', () => CloudAssembly.cleanupTemporaryDirectories());

packages/aws-cdk-lib/package.json

@@ -530,6 +530,7 @@
     "./pipelines/package.json": "./pipelines/package.json",
     "./recommended-feature-flags.json": "./recommended-feature-flags.json",
     "./region-info": "./region-info/index.js",
+    "./testhelpers/jest-autoclean": "./testhelpers/jest-autoclean.js",
     "./triggers": "./triggers/index.js"
   },
   "publishConfig": {

packages/aws-cdk-lib/testhelpers/jest-autoclean.ts

@@ -0,0 +1,15 @@
+/**
+ * A file designed to be used with Jest's `--setupFilesAfterEnv` flag, to automatically clean temporary directories.
+ *
+ * This is an effective alternative to adding an `afterAll()` to every individual test file.
+ *
+ * Can be used as follows:
+ *
+ * ```
+ * $ jest --setupFilesAfterEnv aws-cdk-lib/testhelpers/jest-autoclean
+ * ```
+ */
+import { CloudAssembly } from '../cx-api';
+
+// eslint-disable-next-line @typescript-eslint/unbound-method
+afterAll(CloudAssembly.cleanupTemporaryDirectories);

tools/@aws-cdk/cdk-build-tools/config/jest.config.js

@@ -1,3 +1,13 @@
+const thisPackagesPackageJson = require(`${process.cwd()}/package.json`);
+const setupFilesAfterEnv = [];
+if ('aws-cdk-lib' in thisPackagesPackageJson.devDependencies ?? {}) {
+  // If we depend on aws-cdk-lib, use the provided autoclean hook
+  setupFilesAfterEnv.push('aws-cdk-lib/testhelpers/jest-autoclean');
+} else if (thisPackagesPackageJson.name === 'aws-cdk-lib') {
+  // If we *ARE* aws-cdk-lib, use the hook in a slightly different way
+  setupFilesAfterEnv.push('./testhelpers/jest-autoclean.ts');
+}
+
 module.exports = {
   // The preset deals with preferring TS over JS
   moduleFileExtensions: [
@@ -31,4 +41,6 @@ module.exports = {
   ],
   coveragePathIgnorePatterns: ['\\.generated\\.[jt]s$', '<rootDir>/test/', '.warnings.jsii.js$', '/node_modules/'],
   reporters: ['default', ['jest-junit', { suiteName: 'jest tests', outputDirectory: 'coverage' }]],
+
+  setupFilesAfterEnv,
 };