@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/ssm/README.md

@@ -1,12 +1,11 @@
 # Simulated SSM Parameter Store
 
-Yulin includes a simulated AWS Systems Manager Parameter Store for tests and local development.
-Parameters are stored in memory, versioned on every write, and every operation is authorized by
-simulated IAM.
+Yulin simulates AWS Systems Manager Parameter Store for tests and local development. You can create,
+read, update and delete parameters through the AWS SDK or a CloudFormation template. Parameters are
+stored in memory, each write creates a version, and simulated IAM authorizes every operation.
 
-Only Parameter Store is simulated.
-
-SSM-specific types are imported from the `@kensio/yulin/ssm` subpath.
+Other Systems Manager features, such as Run Command and Session Manager, are not simulated. Import
+SSM-specific types from `@kensio/yulin/ssm`.
 
 ## Writing and reading a parameter
 
@@ -292,8 +291,7 @@ console.log(origins.length); // 2
 
 ## Parameter names
 
-Name validation matches real Parameter Store, because a name it accepts and AWS refuses is a
-deployment failure a passing test would have hidden. A name:
+Parameter names use the same validation rules as AWS. A name:
 
 - may contain letters, digits, `_`, `.`, `-` and `/`
 - must start with `/` if it contains a hierarchy at all
@@ -302,8 +300,8 @@ deployment failure a passing test would have hidden. A name:
 - may not contain spaces between characters, though surrounding spaces are stripped
 - may not make an ARN longer than 1011 characters, counting the ARN prefix for the account and region
 
-A `String` or `StringList` value holds at most 4KB, the standard tier limit. This is the one people
-hit, usually by putting a whole JSON configuration blob in one parameter.
+A `String` or `StringList` value holds at most 4 KB, the standard tier limit. Larger configuration
+documents must be split across parameters or stored elsewhere.
 
 ## Deploying a parameter from CloudFormation
 
@@ -455,9 +453,9 @@ covers that one.
 
 ### A reference the simulation cannot answer
 
-Simulated CloudFormation deploys what it can. A reference naming a parameter that was never created
-resolves to `dummy-value-for-<name>`, and the stack carries on deploying. A template reading
-configuration a test does not care about is still worth deploying for everything else in it.
+When a reference names a parameter that does not exist, simulated CloudFormation substitutes
+`dummy-value-for-<name>` and continues the deployment. This lets a test deploy the rest of a
+template without setting up unrelated configuration.
 
 The substitution is recorded on
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without),
@@ -998,9 +996,9 @@ console.log(read.Parameter?.Value); // "hunter2"
 
 `DescribeParameters` reports the key each `SecureString` is encrypted under as `KeyId`.
 
-## Available functionality
+## Supported operations
 
-Sim SSM currently supports:
+Simulated Parameter Store supports:
 
 - `PutParameterCommand`, creating a parameter or overwriting one
 - `GetParameterCommand`, by name, by `name:version` or by `name:label`
@@ -1026,8 +1024,6 @@ Sim SSM currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - Only standard tier `SecureString` encryption is simulated, which encrypts under the KMS key
   directly. The advanced tier's envelope encryption through the AWS Encryption SDK is left out, and
   `kms:GenerateDataKey` is never needed.

package/docs/services/stepfunctions/README.md

@@ -1,18 +1,18 @@
 # Simulated Step Functions
 
-Simulated Step Functions interprets Amazon States Language and runs a state machine in the same
-process as the code under test. A workflow held in a template as data becomes something a test can
-run and assert on.
+Yulin interprets Amazon States Language and runs Step Functions state machines in the same process
+as the code under test. Tests can start executions, invoke simulated services, advance waits and
+inspect execution history without deploying a workflow.
 
-Types for simulated Step Functions are imported from the `@kensio/yulin/stepfunctions` subpath.
+Import Step Functions-specific types from `@kensio/yulin/stepfunctions`.
 
-## What runs today
+## Supported state machine features
 
-Every state type Amazon States Language defines runs. `Pass`, `Task`, `Succeed`, `Fail`, `Choice`,
-`Wait`, `Parallel` and `Map`.
+All eight state types are supported: `Pass`, `Task`, `Succeed`, `Fail`, `Choice`, `Wait`, `Parallel`
+and `Map`.
 
-The data-flow fields run in full. `InputPath`, `Parameters`, `ResultSelector`, `ResultPath` and
-`OutputPath` apply in that order, reading Reference Paths and the intrinsic functions.
+The data-flow fields `InputPath`, `Parameters`, `ResultSelector`, `ResultPath` and `OutputPath` run in
+that order. They support Reference Paths and intrinsic functions.
 
 A `Task` state invokes a simulated Lambda function, calls an operation on any other simulated
 service, or starts another state machine. A `Resource` this simulator has no answer for is refused
@@ -114,23 +114,21 @@ console.log(described.status); // FAILED
 console.log(described.error); // NotEligible
 ```
 
-A failing execution is recorded on the execution, and the call returns as it would for one that
-succeeded. Simulated EventBridge treats an undeliverable event the same way. An execution failing is
-as often the thing under test as it is a fault, and raising it would fail an unrelated `advanceBy`
-elsewhere in the same test.
+A failed execution records its status and error instead of throwing from `StartExecution`. Read it
+with `DescribeExecution` or the inspection API. This keeps workflow failure available for
+assertions.
 
 ## Invoking a Lambda function
 
 A `Task` state invokes a simulated Lambda function, through either of the two `Resource` forms CDK's
 `LambdaInvoke` emits.
 
-`arn:aws:states:::lambda:invoke` is the integration Step Functions optimises. The state is talking to
-the Lambda API, so its `Parameters` are an `Invoke` request (`FunctionName` names the function and
-`Payload` carries what it is sent) and its result is an `Invoke` response, with the handler's answer
-under `Payload`.
+With `arn:aws:states:::lambda:invoke`, `Parameters` has the shape of a Lambda `Invoke` request.
+`FunctionName` selects the function, `Payload` contains its input, and the handler result appears
+under `Payload` in the task output.
 
-A function ARN sends the state's own input to the handler and answers with what the handler
-returned. CDK writes this form for `payloadResponseOnly`.
+A function ARN sends the state input directly to the handler and uses the handler result as the task
+output. CDK emits this form when `payloadResponseOnly` is enabled.
 
 ```typescript sim-step-functions-task
 /**
@@ -1334,7 +1332,7 @@ reference contradicts itself here, listing a differing role ARN under `StateMach
 while the operation's own note says the difference is ignored. The note is the more specific of the
 two and is what this follows.
 
-## Still to come
+## Limitations
 
 - Distributed Map, with `ItemReader`, `ResultWriter` and the `ToleratedFailure` fields.
 - The `.sync` pattern, task tokens and activities.

package/docs/services/sts/README.md

@@ -1,16 +1,12 @@
 # Simulated STS
 
-Yulin includes a simulated STS (Security Token Service) for tests and local development.
-
-Sim STS is used through `SimAws` as `simAws.sts()`, scoped to the Account making the assume request.
-It simulates assuming IAM Roles. An assume request is evaluated against
-[simulated IAM](https://yulinsim.dev/services/iam/) policies, and a request that passes issues temporary session credentials
-that the rest of the simulated environment authenticates like real AWS credentials.
+Yulin simulates `AssumeRole` and `GetCallerIdentity`. Access the service through `simAws.sts()` or an
+intercepted `STSClient`.
 
 ## Basic usage
 
-Create a Role whose trust policy allows the Account to assume it, then assume it through STS. An
-omitted caller defaults to the Account root principal.
+Create a role with a trust policy, then call `assumeRole`. A request with no caller runs as the
+account root.
 
 ```typescript sim-sts-assume-role
 /**
@@ -50,23 +46,28 @@ console.log(assumeRoleOutput.Credentials?.AccessKeyId);
 console.log(assumeRoleOutput.Credentials?.Expiration);
 ```
 
-The output matches the AWS shape. `AssumedRoleUser.Arn` is the session ARN, such as
+`AssumedRoleUser.Arn` is the session ARN, such as
 `arn:aws:sts::123456789012:assumed-role/TargetRole/test-session`, and `Credentials` carries the
 temporary `AccessKeyId`, `SecretAccessKey`, `SessionToken`, and `Expiration`.
 
-The issued credentials are registered with the target Account's sim IAM. They authenticate later
-simulated requests, for example as the `caller` of an IAM authorization attempt, where identity
-policies come from the underlying Role. See [the sim IAM docs](https://yulinsim.dev/services/iam/#sts-assumerole-sessions) for a
-full example. Credentials missing their session token, or used after `Expiration`, are rejected with
-an AWS-like invalid-credentials error.
+Yulin registers the credentials with simulated IAM in the target account. Later requests use the
+role's identity policies. See [STS sessions in simulated IAM](https://yulinsim.dev/services/iam/#sts-assumerole-sessions).
+Credentials fail after `Expiration` or when the session token is missing.
+
+`DurationSeconds` defaults to 3,600 seconds and must be a positive integer.
+
+## Reading the current identity
 
-`DurationSeconds` controls the session lifetime and defaults to 3600 seconds (one hour). It must be
-a positive integer.
+`getCallerIdentity` reports the caller's ARN, account ID and user ID. It handles account roots, IAM
+users and assumed-role sessions. The intercepted and served STS APIs also support
+`GetCallerIdentityCommand`.
+
+An unattributed request reports the configured default caller, or the account root when no default
+caller is configured. An anonymous caller receives `AccessDenied`.
 
 ## Role-to-Role assumption
 
-Pass a caller to assume a Role as a specific principal. As in real AWS, both sides of the request
-are then evaluated:
+Pass `caller` to assume a role as a specific principal. STS checks both sides of the request:
 
 - The target Role's trust policy must allow the caller to perform `sts:AssumeRole`
 - A non-root caller also needs an identity policy allowing `sts:AssumeRole` on the target Role's
@@ -144,33 +145,25 @@ const assumeRoleOutput = await account.sts().assumeRole(
 console.log(assumeRoleOutput.AssumedRoleUser?.Arn);
 ```
 
-STS throws an AWS-like access-denied error if either side denies the request, which happens when the
-trust policy does not cover the caller, the caller has no identity policy allowing `sts:AssumeRole`,
-or an explicit `Deny` matches. The error has a `403` status code and names the `sts:AssumeRole`
-action and the target Role ARN. No session is created.
+If either check fails, STS raises a 403 access-denied error naming `sts:AssumeRole` and the target
+role ARN. No session is created.
 
-Cross-Account assumption works the same way. Create the source and target Roles in different
-simulated Accounts of the same `SimAws` instance, and call `assumeRole` on the source Account's
-`sts()`. The issued session belongs to the target Role's Account.
+Cross-account assumption uses the same checks. Call `assumeRole` through the source account. The
+session belongs to the target role's account.
 
 ## Role chaining
 
-A process that assumes a Role and then assumes a second one from that session is chaining Roles. The
-caller of the second request is the session, and the Role it holds the permissions of is what both
-sides of the decision are written against. The trust policy of the target names that Role, and the
-identity policy allowing `sts:AssumeRole` belongs to it.
+For role chaining, use the first session as the caller of the second `assumeRole` request. The target
+trust policy names the first role, and that role needs identity permission to assume the target.
 
-Both ARNs of a session are matched against a `Principal`, so a trust policy naming either the Role
-or one particular session admits it. AWS recommends naming the Role, and a session name is often
-decided at run time rather than written into a policy.
+A trust policy may name the role ARN or one assumed-role session ARN. Prefer the role ARN when the
+session name is chosen at run time.
 
-Chaining over a served endpoint works the same way. Credentials from the first request sign the
-second, and the caller they resolve to carries the Role along with the session.
+The served endpoint resolves session credentials in the same way.
 
 ## ExternalId
 
-A trust policy can require an external ID through the `sts:ExternalId` condition key. The
-`ExternalId` supplied to `AssumeRoleCommand` is matched against it.
+A trust policy can require `sts:ExternalId`. Pass the matching `ExternalId` to `AssumeRoleCommand`.
 
 ```typescript sim-sts-external-id
 /**
@@ -214,14 +207,14 @@ const assumeRoleOutput = await account.sts().assumeRole(
 console.log(assumeRoleOutput.AssumedRoleUser?.Arn);
 ```
 
-An omitted or mismatched `ExternalId` leaves the trust-policy condition unmatched. The assume
-request is denied.
+An omitted or mismatched value denies the request.
 
 ## Available functionality
 
 Sim STS currently supports:
 
 - `AssumeRoleCommand`
+- `GetCallerIdentityCommand`
 - Trust-policy evaluation against the target Role's assume-role policy document
 - Identity-policy evaluation of the source caller, requiring `sts:AssumeRole` permission on the
   target Role
@@ -231,15 +224,9 @@ Sim STS currently supports:
 - Temporary credentials registered with the target Account's sim IAM, including session-token and
   expiry validation
 
-Unsupported STS options may be ignored or may throw errors depending on whether the simulator needs
-them to model the requested behaviour.
-
 ## Limitations
 
-Sim STS models Role assumption. Notable gaps:
-
-- `AssumeRoleCommand` is the only supported command. There is no `GetCallerIdentity`, federation, or
-  web-identity support
+- Federation, web identity and session-token commands are unsupported.
 - Session policies (`Policy` / `PolicyArns`), tags, and `SourceIdentity` requests are not evaluated
 - Condition support in trust policies is limited to the operators supported by
   [sim IAM](https://yulinsim.dev/services/iam/#policy-conditions)

package/docs/services/wafv2/README.md

@@ -1,16 +1,11 @@
 # Simulated WAFv2
 
-Yulin includes a simulated AWS WAFv2 for tests and local development. It holds web ACLs, IP sets and
-regex pattern sets, and it evaluates a request against a web ACL's rules to reach a decision. A test
-can assert that a request to `/admin` is blocked and one to `/` is allowed, without an AWS account
-and without a distribution in front of anything.
+Yulin simulates AWS WAFv2 web ACLs, IP sets and regex pattern sets for tests and local development.
+You can evaluate a `Request` directly or associate a web ACL with a simulated API Gateway REST API,
+Cognito user pool or CloudFront distribution. Each request is checked against the web ACL before
+the protected service handles it.
 
-A web ACL can also go in front of what serves the requests. A simulated API Gateway REST API stage
-and a simulated Cognito user pool each take one through `AssociateWebACL`, and a simulated
-CloudFront distribution takes one through its own `WebACLId`. The requests that stage, pool or
-distribution serves are then put through the web ACL's rules.
-
-WAFv2 specific types are imported from the `@kensio/yulin/wafv2` subpath.
+Import WAFv2-specific types from `@kensio/yulin/wafv2`.
 
 ## Deciding what happens to a request
 
@@ -91,11 +86,11 @@ carrying the status, the body and any headers the rule named.
 
 ## Rules run in priority order
 
-Rules are evaluated in ascending `Priority` and not in the order the list was written. The first
-rule that matches and carries a terminating action (`Allow` or `Block`) decides the request.
+Rules are evaluated by ascending `Priority`, regardless of their order in the input list. The first
+matching rule with an `Allow` or `Block` action decides the request.
 
-A `Count` action records the match and lets the next rule have a look. That is how a rule is staged
-before it is turned on, and `countedRuleNames` is what a test asserts against.
+A `Count` action records the match and continues to the next rule. Tests can inspect
+`countedRuleNames` before changing a rule to `Allow` or `Block`.
 
 ```typescript sim-wafv2-count
 /**
@@ -154,8 +149,8 @@ whatever serves the request has usually read it by the time WAF gets a look.
 
 ## What a statement can inspect
 
-A statement reads one part of the request, applies the rule's text transformations to it, and tests
-what comes out.
+A statement selects part of the request, applies its text transformations, and then tests the
+result.
 
 The parts a statement can be pointed at are `UriPath`, `QueryString`, `SingleQueryArgument`,
 `AllQueryArguments`, `SingleHeader`, `Headers`, `Cookies`, `Method` and `Body`. `Headers` and
@@ -1371,7 +1366,7 @@ Tags, logging, sampled requests and CloudWatch metrics for a web ACL are not sim
 `AssociationConfig`, `DataProtectionConfig`, `OnSourceDDoSProtectionConfig` and `ApplicationConfig`
 are refused for the same reason, each naming what it would have configured.
 
-## Simulated commands
+## Supported operations
 
 `CreateWebACL`, `GetWebACL`, `UpdateWebACL`, `ListWebACLs`, `DeleteWebACL`, `CreateIPSet`,
 `GetIPSet`, `UpdateIPSet`, `ListIPSets`, `DeleteIPSet`, `CreateRegexPatternSet`,

package/docs/testing/README.md

@@ -0,0 +1,228 @@
+# Test suite setup
+
+Run one Yulin environment for an application's test suite. Create the simulation, deploy the
+application's infrastructure, and install AWS SDK interception once. Every test then interacts with
+the same simulated account and resources.
+
+This is the recommended setup. It matches the way a suite uses a shared AWS account or a
+container-based simulator such as LocalStack. Creating a new Yulin environment for every test or
+test file is supported, but it should be reserved for cases that need a blank simulated account.
+
+The simulated clock is the main exception. A suite-wide `SimAws` has one clock, so a test that moves
+it changes time for every resource in that environment. Keep the majority of tests in the shared
+environment without changing its clock. Put clock-controlling tests in a smaller isolated group.
+
+## Split the Vitest suite
+
+Yulin holds state in the process that created it. Vitest must run the Yulin tests in one worker for
+all shared files to reach the same environment. Give that project disabled file parallelism and file
+isolation, then load a setup module before each test file.
+
+The second project below matches files ending in `.clock.test.ts`. Those tests do not load the shared
+setup and can create isolated Yulin environments:
+
+```typescript testing-vitest-config
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: "shared Yulin",
+          include: ["test/**/*.test.ts"],
+          exclude: ["test/**/*.clock.test.ts"],
+          fileParallelism: false,
+          isolate: false,
+          setupFiles: ["./test/setup-yulin.ts"],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: "isolated Yulin clock",
+          include: ["test/**/*.clock.test.ts"],
+        },
+      },
+    ],
+  },
+});
+```
+
+Vitest executes a `setupFiles` entry before every test file. With isolation disabled, modules
+imported by that entry stay cached in the worker. Put the Yulin initialization in an imported module
+to make it run once.
+
+See Vitest's documentation for [`setupFiles`](https://vitest.dev/config/setupfiles),
+[`fileParallelism`](https://vitest.dev/config/fileparallelism), and
+[`isolate`](https://vitest.dev/config/isolate).
+
+## Create and deploy the shared environment
+
+Put the suite environment in a module such as `test/yulin-environment.ts`. Intercept client classes
+used by the application and deploy its synthesized CDK cloud assembly:
+
+```typescript testing-shared-yulin-environment
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { S3Client } from "@aws-sdk/client-s3";
+import type { SimAws } from "@kensio/yulin";
+import { SimSdk } from "@kensio/yulin/sdk";
+
+interface YulinTestEnvironment {
+  readonly simAws: SimAws;
+  readonly simSdk: SimSdk;
+  readonly uploadsBucketName: string;
+}
+
+type YulinTestGlobal = typeof globalThis & {
+  yulinEnvironment?: Promise<YulinTestEnvironment>;
+};
+
+const testGlobal = globalThis as YulinTestGlobal;
+
+// oxlint-disable-next-line unicorn-js/prefer-top-level-await -- The shared promise prevents setup from running again before another test file.
+export const yulin = await (testGlobal.yulinEnvironment ??= startYulin());
+
+async function startYulin(): Promise<YulinTestEnvironment> {
+  const simSdk = new SimSdk();
+  simSdk.intercept(DynamoDBClient);
+  simSdk.intercept(S3Client);
+
+  const stacks = await simSdk.simAws.cloudFormation().deployCdkOut({
+    directoryPath: "cdk.out",
+    stackNames: ["ApplicationStack"],
+  });
+  const appStack = stacks.get("ApplicationStack");
+
+  if (appStack === undefined) {
+    throw new Error("ApplicationStack was not deployed");
+  }
+
+  process.once("exit", () => {
+    simSdk.restoreAll();
+  });
+
+  return {
+    simAws: simSdk.simAws,
+    simSdk,
+    uploadsBucketName: appStack.output("UploadsBucketName"),
+  };
+}
+```
+
+Use the same templates that the application deploys. `deployCdkOut(...)` can deploy the whole cloud
+assembly or the named application Stacks. Read generated resource names from stack outputs or
+resource accessors after deployment.
+
+The configured setup entry only needs to import that module:
+
+```typescript
+// test/setup-yulin.ts
+import "./yulin-environment.js";
+```
+
+Do not put the initialization directly in `setup-yulin.ts`. Vitest executes that file for every test
+file, even when isolation is disabled.
+
+## Use the environment from every test
+
+Application code continues to construct and send through ordinary AWS SDK clients. Class-level
+interception routes all of them to the suite's Yulin environment.
+
+A test that needs direct access can import the shared environment:
+
+```typescript
+import { randomUUID } from "node:crypto";
+
+import {
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { expect, it } from "vitest";
+
+import { yulin } from "../yulin-environment.js";
+
+it("stores an upload", async () => {
+  const key = `test-uploads/${randomUUID()}.txt`;
+  const s3 = new S3Client({ region: "eu-west-2" });
+
+  await s3.send(
+    new PutObjectCommand({
+      Bucket: yulin.uploadsBucketName,
+      Key: key,
+      Body: "an upload",
+    }),
+  );
+
+  const stored = await yulin.simAws
+    .region("eu-west-2")
+    .s3()
+    .getObject(
+      new GetObjectCommand({
+        Bucket: yulin.uploadsBucketName,
+        Key: key,
+      }),
+    );
+
+  expect(await stored?.Body?.transformToString()).toBe("an upload");
+});
+```
+
+The `SimAws` object is mainly useful for preparing input state and reading state back in assertions.
+Exercise the application through its normal interfaces whenever possible.
+
+## Keep tests independent in shared state
+
+Shared infrastructure does not require tests to depend on one another. Give each test's records,
+object keys, user names, and other mutable data unique values. Read CloudFormation-generated names
+from the deployed stack. Avoid assertions that assume the simulated account contains no other data.
+
+Keep `beforeEach` for the records a test needs. A per-file `beforeAll` can prepare data used by every
+test in that file. Leave the suite's stacks and SDK interception in place until the worker exits.
+
+Tests run sequentially with `fileParallelism: false`. If a test uses `it.concurrent`, its data still
+needs unique identifiers because those cases share the same environment at the same time.
+
+## Give clock-controlling tests their own environment
+
+Every service in a `SimAws` reads the same simulated clock. Calling `advanceBy(...)` can expire
+credentials, delete resources whose retention period has passed, and run scheduled work anywhere in
+the environment. Resetting the clock afterwards cannot reverse those changes.
+
+Tests in the shared project should treat the clock as read-only. Put a test that calls `freeze()`,
+`setTo(...)`, `advanceBy(...)`, or `resume()` in a `.clock.test.ts` file and create a fresh environment
+inside the test:
+
+```typescript
+import { SimAws, SimFixedClock } from "@kensio/yulin";
+import { it } from "vitest";
+
+it("expires a session", async () => {
+  const simAws = new SimAws({
+    clock: new SimFixedClock(new Date("2026-09-04T09:00:00.000Z")),
+  });
+
+  // Deploy only the infrastructure this clock-controlling test needs.
+
+  await simAws.clock().advanceBy({ minutes: 20 });
+
+  // Assert the behaviour after the time change.
+});
+```
+
+Create a `SimSdk` around that `SimAws` when application code uses SDK clients. Restore its
+interceptions at the end of the test. The [simulated time guide](https://yulinsim.dev/time/) describes
+what moving the clock runs and changes.
+
+## When to create another environment
+
+A fresh `SimAws` or `SimSdk` is useful when the empty environment is part of the behaviour under
+test, or when the test needs to control simulated time. Yulin's own service unit tests are another
+example because they test resource creation and account isolation directly.
+
+Vitest workers cannot share an in-memory `SimAws`. A suite that keeps file parallelism creates one
+environment per worker. Put Yulin-based application tests in a Vitest project with
+`fileParallelism: false` when the rest of the unit suite should remain parallel.

package/docs/time/README.md

@@ -3,6 +3,16 @@
 Each `SimAws` has its own clock. Yulin uses that clock for resource timestamps, expiry checks, and
 scheduled work.
 
+## Isolate tests that control time
+
+A shared [test suite environment](https://yulinsim.dev/testing/) also has one shared clock. Most
+tests should use that environment without calling `freeze()`, `setTo(...)`, `advanceBy(...)`, or
+`resume()`.
+
+Put tests that control simulated time in a separate test group. Give each of those tests its own
+`SimAws` or `SimSdk`, along with the infrastructure it needs. A clock change then affects only that
+test's environment. The rest of the suite can keep sharing one deployment and SDK interception.
+
 ## Start at a known time
 
 A new simulation follows the system clock by default. Pass a `SimFixedClock` when a test needs an

package/llms.txt

@@ -57,4 +57,5 @@ The same pages are on the web at https://yulinsim.dev/ for whichever release is
 - [Non-AWS dependencies](docs/non-aws-dependencies/README.md): Dependencies Yulin does not simulate usage docs
 - [Serving on localhost](docs/serve/README.md): Serving simulated AWS on localhost usage docs
 - [Simulated time](docs/time/README.md): Simulated time usage docs
+- [Test suite setup](docs/testing/README.md): Sharing one Yulin environment across a test suite
 - [Terraform](docs/terraform/README.md): Deploying Terraform into simulated AWS usage docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.7",
+  "version": "1.21.9",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",