From 5010cfea86dcccb4f59a53b4b75267013ffe40c6 Mon Sep 17 00:00:00 2001 From: Graham Campbell Date: Tue, 9 Jun 2026 01:14:37 +0100 Subject: [PATCH 1/2] Align Compose test guide with OSLS --- test/README.md | 47 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 9 deletions(-) diff --git a/test/README.md b/test/README.md index bce80b7..1464796 100644 --- a/test/README.md +++ b/test/README.md @@ -1,16 +1,18 @@ -# Compose Test Guide +# How To Run, Organize, And Write Tests -The Compose test suite is mostly focused unit tests. Prefer small fakes and direct collaborators unless the test is specifically about command orchestration, component graph execution, process behavior, or a module-load seam. +This document describes the expected style for new and updated Compose tests. -## Commands +Prefer the smallest harness that exercises the behavior under test without hiding important Compose interactions. -Run the full unit suite: +## Unit tests + +Tests use [Mocha](https://mochajs.org/) and can be run with: ```sh npm test ``` -Run focused unit tests: +Use focused unit test runs when working on a small area: ```sh npx mocha --require ./test/mocha/bootstrap.cjs --require ./test/mocha/root-hooks.cjs --timeout 10000 --node-option unhandled-rejections=strict "test/unit/src/components-service.test.js" @@ -25,7 +27,32 @@ npm run lint:updated npm run prettier-check:updated ``` -## Runtime Sandbox +When creating a new test, name the top-level `describe` after the path to the file, as the existing unit tests do. + +### Existing Test Examples + +- [Component graph orchestration](./unit/src/components-service.test.js) +- [Framework child process seams](./unit/components/framework/index.test.js) +- [Entrypoint and process behavior](./unit/src/index.test.js) +- [AWS command behavior](./unit/src/state/utils/get-state-bucket-region.test.js) +- [AWS client config behavior](./unit/src/state/S3StateStorage.test.js) +- [Filesystem utility behavior](./unit/src/utils/fs.test.js) + +Prefer small, focused test refactors that preserve behavior while moving toward the style documented here. + +### Test Style Decision Rule + +Prefer a small fake or direct collaborator when the subject is a pure helper, formatter, path/fs utility, state storage operation, or narrow SDK wrapper. + +Use orchestration helpers when the behavior depends on initialized Compose context, service graph execution, command routing, or state storage wiring. + +Use `proxyquire` when the test is about a module-boundary seam or require-time behavior. Do not use it just to avoid passing a plain fake to code that already accepts one. + +Direct `new Context(...)` is allowed when `Context` behavior is the subject, or when a helper would hide the behavior being asserted. + +Compose does not have an `osls`-style `runServerless` helper. Do not add a broad lifecycle harness unless the tests need one. + +## Runtime Sandbox And Cleanup Mocha root hooks restore common process state before and after tests: @@ -47,11 +74,11 @@ The root hooks do not restore every global mutation. Keep local cleanup for: | stream method overrides | Yes | | module singletons and static class properties | Yes | -## Proxyquire +Use [`test/lib/env.js`](./lib/env.js) when a test needs to clear a specific set of environment variables before the assertion and restore them afterward. -`proxyquire` is acceptable when the test is about a module-boundary seam or require-time behavior. Do not use it just to avoid passing a plain fake to code that already accepts one. +## Proxyquire -Good uses: +Good `proxyquire` uses in this repo include: | Seam | Example | | ------------------------------ | -------------------------------------------- | @@ -101,6 +128,8 @@ Do not remove compatibility behavior such as `externalBucket`, `existingBucket`, Use `test/lib/fs.js` helpers for file setup and teardown. The test suite already runs in a sandbox cwd. Use per-test temp directories when a test needs independent state or filesystem behavior under a specific root. +Keep symlink skip behavior explicit so Windows symlink permission failures call `this.skip()` correctly. + ## Review Checklist Before opening a PR: From d81d7d16f0b8e34fed5e72fd3838e247849d3ba1 Mon Sep 17 00:00:00 2001 From: Graham Campbell Date: Tue, 9 Jun 2026 01:15:33 +0100 Subject: [PATCH 2/2] Use title case in test guide headers --- test/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/README.md b/test/README.md index 1464796..2d546f9 100644 --- a/test/README.md +++ b/test/README.md @@ -4,7 +4,7 @@ This document describes the expected style for new and updated Compose tests. Prefer the smallest harness that exercises the behavior under test without hiding important Compose interactions. -## Unit tests +## Unit Tests Tests use [Mocha](https://mochajs.org/) and can be run with: