Align Compose test guide with OSLS

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: