aws / aws/aws-cdk

assertions: Jest temp-directory cleanup (from #36043) is undocumented and the docstring points at a non-existent module

Open Beginner friendly
#38,199 1 comment 0 reactions 0 assignees View on GitHub
@aws-cdk/assertions documentation effort/small p2
Dominant language
TypeScript
Stars
12.9k
Forks
4.6k
Avg merge
2d 3h
Merged PRs (30d)
83

Description

### Describe the issue

#36043 fixed the framework so the throwaway Cloud Assemblies that `Template.fromStack()` (and any synth without an explicit `outdir`) write into the OS temp directory are registered and deleted on Node process exit. It also shipped `aws-cdk-lib/testhelpers/jest-autoclean` and `CloudAssembly.cleanupTemporaryDirectories()` for environments where Node's `exit` event does not fire.

Node's `exit` event does not fire under Jest (jestjs/jest#10927), which is the runtime almost all CDK users run their assertion tests in. So for downstream Jest users the cleanup only happens if they opt in, and there are two documentation gaps that make that opt-in undiscoverable:

1. The `assertions` README (the headline entry point, via `Template.fromStack()`) does not mention the leak or the cleanup helper at all. On a busy dev or CI machine the leaked `cdk.out*` directories accumulate into the tens of thousands and tens of GiB and eventually fill the disk (see the closed-stale reports #29368, #11730, #32255, all the same symptom).
2. The one place the opt-in is documented, the `CloudAssembly.cleanupTemporaryDirectories()` docstring, points at `aws-cdk-lib/testhelpers/jest-cleanup`, but the actual exported helper is `aws-cdk-lib/testhelpers/jest-autoclean`. Copying that config line gives a "module not found" error.

### Links

- `packages/aws-cdk-lib/assertions/README.md` (the `Template.fromStack()` section, no cleanup note)
- `packages/aws-cdk-lib/cx-api/lib/legacy-moved.ts` (the `cleanupTemporaryDirectories` docstring with the wrong `jest-cleanup` module name)
- Related: #36043 (the framework fix), and closed-stale symptom reports #29368, #32255, #11730

Contributor guide

Open the contributing guide

Research direction

Start with the Template.fromStack() section in packages/aws-cdk-lib/assertions/README.md and the cleanupTemporaryDirectories docstring in packages/aws-cdk-lib/cx-api/lib/legacy-moved.ts. Compare the documented helper name with the exported aws-cdk-lib/testhelpers/jest-autoclean entry point and review #36043 for context. Done means both locations accurately explain Jest cleanup and the documented module path works.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.