Testing with Yulin

Yulin (@kensio/yulin) simulates AWS in process, in memory, with no network and no AWS account. This skill is how to use it well. It serves isolated-testing-style, the general argument for simulation over stubs. Each rule says what it buys, and a case that does not want that trade can go the other way knowingly.

Treat Yulin as suite infrastructure, in the same way tests treat an AWS account or a LocalStack container. Create one simulation, deploy the application once and install SDK interception once in the Vitest suite setup. Every test talks to that shared environment. Randomised resource names and identifiers keep tests independent while the simulated AWS state remains alive for the whole suite. This is the default for tests that leave the simulation clock alone. Put the smaller set of tests that change simulated time in an isolated group, with their own Yulin setup.

For the API read node_modules/@kensio/yulin/llms.txt. It indexes the 45 markdown pages beside it under node_modules/@kensio/yulin/docs/, one per simulated service and per feature guide, documenting the version installed. Open the page it names for the service in hand and grep it for the operation or property, since Cognito runs to 210 KB with DynamoDB and Lambda close behind. Where the package is absent, or predates the 1.20.x that started carrying it, yulinsim.dev/llms.txt has the same index for the current release (drop the llms.txt for HTML).

Use what Yulin already gives you

The most common way to go wrong is to build something on top of it. The failure looks like a TestAwsEnvironment class, a setupSimulatedAws() helper returning six things, a factory per service, or a beforeEach that reassembles the world.

Yulin is built to be used directly. new SimAws() and new SimSdk() are plain constructors with no side effects, no network, no cleanup and no awaiting. Service accessors take the same Command objects the SDK does. The suite setup creates these objects once. deployTemplateFile is the environment, and the tests import the shared simulation objects directly.

The setup constructs, deploys and intercepts. A test exercises the application and reads the shared simulation back. A wrapper around any of those steps hides what the reader needs to see. The setup can be a small module returning the simulation objects themselves. Once it wants a class, an options interface or a directory, it has become a second product.

One CDK app behind the tests, local dev and production

Describe the infrastructure once in CDK and let the synthesized output drive all three. Deploy the template files cdk synth wrote, one of them or all of them, and talk to the simulation the way production talks to AWS.

const stack = await simAws.region("eu-west-2").cloudFormation().deployTemplateFile({
  templatePath: "cdk.out/SiteStack.template.json",
  stackName: "site-stack",
});

await stack.waitForDeployComplete();

The test suite deploys this template once during its shared Yulin setup. Individual tests use the deployed resources and do not deploy their own copies.

A hand-written template only tests itself, and a dev environment building its own buckets is a third description whose drift shows up as a bug reproducing in one place of the three. Infrastructure belongs in the CDK app even when only a test needs it.

Do not hand-roll a wrapper that reads the file and calls deployTemplate. deployTemplateFile locates the cloud assembly beside the file, and that is how staged CDK assets resolve. A wrapper reading the JSON fails anything needing one (a Custom::CDKBucketDeployment, a Code.fromAsset function) with No CDK assets manifest is available. Two options make a wrapper unnecessary.

• transform is given the parsed template and answers with the one to deploy, on the deployment and on every re-read. Use it for what a simulation genuinely cannot resolve, such as an ARN carrying a real account.
• watch re-applies the file when it changes, updating the stack in place and leaving untouched resources holding what they held. For dev servers, where a cdk synth becomes a stack update without restarting the process.

await simAws.cloudFormation().deployTemplateFile({
  templatePath: "cdk.out/SiteStack.template.json",
  transform: withRealAccountArnsResolved,
  watch: { onUpdated: () => srv.reload() },
});

The watched file is the one CDK wrote, and the adaptation re-applies on every read.

stack.output("SiteBucketName") answers a resolved Output narrowed to a string, throwing on one the template never declared. Do not hand-roll that reader. A failed cdk synth leaves the previous template in cdk.out with the tests still passing against it, so check the synthesized JSON changed before concluding anything from a construct change.

Read a generated name back, never write one out

A Resource whose template leaves its name out is named <stack name>-<logical ID>-<tail>, as an account names one. The tail is twelve lowercase hex characters derived from the other two parts, standing in for the twelve random ones real CloudFormation appends. Where the two parts overrun the service’s limit, thirteen characters of it go to the tail and its hyphen and the rest is shared between them (a 64 character limit leaves 25 each). The trimmed stack name is what an IAM policy scoped by resource prefix matches, and a deploy Role allowed an action on MyVeryLongStackName-* is refused here as an account refuses it.

The same template under the same stack name generates the same name every time. That is the one property tempting a test to write the name out. Read it back instead, from a Ref, from an Fn::GetAtt attribute or from the accessor of the service holding it. Names CloudFormation generates covers the tail and the trimming.

An ECS container binding has no way round this. The family CloudFormation generates for an unnamed task definition ends in a tail only a deployment reveals. Name the task definition Resource with the logicalId binding form.

Register what the app looks up, deploy what the app creates

A CDK app pinning an identifier as a literal string across stacks raises the question of where the simulated resource carrying it comes from. Yulin stands one up at a chosen id with simAws.route53().registerHostedZone({ id, name }), simAws.acm().registerCertificate({ arn, domainName }), simAws.cognitoIdentityProvider().registerUserPool({ id, name }) and registerUserPoolClient.

A registration creates a resource in place of the app creating one. It suits HostedZone.fromLookup or a certificate issued by hand outside the app. A resource some stack in the same app creates wants deploying instead, since a registration takes its configuration from somewhere other than the deployed template. Substitute in a transform only where a deployed resource cannot be given the id its template names.

Route 53 needs least of this. An AWS::Route53::RecordSet naming a hosted zone id no zone holds gets one registered under that id as the record is created, taking its name from the records naming it. Register it yourself only where a test depends on that name.

Deploy a whole cloud assembly with deployCdkOut

deployCdkOut deploys the Stacks a cdk.out holds, each into the region its own environment names in the assembly manifest, retiring the per-stack region constants. A Stack synthesized with env: { region: "us-east-1" } lands in simulated us-east-1 wherever the call was made from, and one without env takes the region of the scope it was asked through.

const stacks = await simAws.cloudFormation().deployCdkOut({
  directoryPath: "cdk.out",
  stackNames: ["DnsStack", "SiteStack"], // Stack names or CDK artifact IDs.
  stackOptions: {
    SiteStack: {
      bindings: [{ logicalId: "UploadFunction", handler: uploadHandler }],
      transform: (template, deployed) =>
        withSimulatedCertificate(template, deployed.get("DnsStack")?.output("SiteCertificateArn")),
    },
  },
});

stackNames picks part of an assembly, which most apps need, since most also synthesize a deployment pipeline. stackOptions carries the bindings, parameters and transform that deployTemplateFile takes for one template, keyed the same way. Its transform is handed the Stacks the same call already deployed, so a Stack consuming a sibling’s value stays inside one call. Two Stacks passing a plain string between them declare no dependency for the manifest to carry, and their order in stackNames is what puts the value there in time.

Intercept real SDK clients, never hand-roll stubs

SimSdk replaces the send method of an AWS SDK client class or instance. Real clients then answer from the simulation, and the code under test uses the SDK exactly as it does in production.

const simSdk = new SimSdk({ simAws });
simSdk.intercept(SecretsManagerClient); // Every instance, including ones made later.

A stub asserts that your code called something. The simulator asserts that it called the service correctly. A stub has no naming rules and verifies no signatures. A malformed Secrets Manager name or a wrongly computed Cognito SECRET_HASH passes it and fails in production.

Intercept the class in most cases, since the code under test usually constructs its own clients. Install that class interception once in the suite setup. A class interception is process-wide (it shadows send on the class prototype) and refuses a second install while the first is live, with SimSdkAlreadyInterceptedError. Repeated interception in beforeEach or in each test file is both unnecessary and an error when those files share a worker. Intercept an instance only when one specific client should reach Yulin.

Whichever it is, it has to be the client the code actually calls. A DynamoDBDocumentClient built over a DynamoDBClient is what the code sends through, and the document client is the one to intercept. Every Command routes to the simulation by default, and an allow list of Command classes narrows that where something else should handle the rest.

Keep the suite’s SimSdk alive for as long as the suite. Worker exit normally removes its process-wide patches. Call simSdk.restoreAll() if the process will continue doing other work. using simSdk = new SimSdk() and interception.restore() remain useful for a deliberately short-lived simulation. Each SimSdk owns a SimAws, reachable as simSdk.simAws, and new SimSdk({ simAws }) shares an existing one.

A fake accepts any request the simulator would refuse

A fake S3 client stubbing send with canned ListObjectsV2 pages, asserted on through the continuation tokens it recorded, passes for code that built its command without a Bucket. Simulated S3 paginates for real, down to the ETag a real multipart upload produces, and configureMaxKeysPerPage lowers the page size so that a bucket of two objects makes a caller walk a continuation. The residue is small, and a test reaching for a fake to get an answer the service never sends should say so in a comment.

Freeze the clock and advance it deliberately

Each SimAws carries its own clock, independent of the host and of every other simulation in the process. Start it frozen and move it only on purpose:

const simAws = new SimAws({
  clock: new SimFixedClock(new Date("2026-07-26T09:00:00.000Z")),
});

// Given a session that has run out while the caller was idle.
await simAws.clock().advanceBy({ minutes: 20 });

Time-dependent behaviour then becomes something a test asserts on in microseconds, and a good deal of the simulation keys off that clock. EventBridge rules and Scheduler schedules fire only when time is advanced past them, DynamoDB items pass their TTL, Secrets Manager deletions come due, AssumeRole sessions expire, Lambda event source mappings re-poll, and inside a simulated Lambda Date.now() and new Date() report simulated time. The clock stub isolated-testing-style allows is unnecessary here, since advancing this one exercises the real expiry rules of the services around it as well as the code’s own arithmetic.

simAws.clock().resume() tracks the underlying clock and simAws.clock().isFrozen reports the mode. Running mode suits a local dev server, and a test usually wants an advance.

Give clock-changing tests their own simulation

The clock is part of a SimAws instance’s state. Tests sharing that instance also share its current time and whether it is frozen or running. One test advancing or resuming the clock therefore changes the environment underneath every other test in that group. Randomised resource names cannot isolate this change.

Most tests should use the suite simulation without changing its clock. Put tests that advance the clock or change its mode in a separate Vitest project or file group. Give each of those tests a fresh SimAws, deployment and interception layer. Each test can then control time without affecting another test. A small group may share one isolated simulation when its cases deliberately follow the same timeline.

Assert by reading the simulation back

The simulation holds real state. After exercising the code, ask the service what happened:

// Then the upload is in the bucket, under the key the handler chose.
const object = await simAws.s3().getObject(new GetObjectCommand({ Bucket: bucket, Key: key }));

A call-count assertion holds only for today’s implementation. A state assertion holds however the handler is rewritten, and it fails if the call was made in a way the real service would have rejected. In the shared suite environment, read the resource named by the test’s random identifier. Do not list the whole service and assume no other test has left state there.

The accessors sit on more than one scope. simAws.region(name) carries some of the services and simAws.region(name).account() carries all of them (logs() among the account-only ones), so look on the other scope before concluding a service is missing. Each also takes a plain { input: { ... } } in place of a Command object. An assertion can then read a service back without adding an @aws-sdk/client-* package the production code has no use for.

Drive requests into the simulation

Reading state back covers the resources. SimAwsHttp from @kensio/yulin/serve covers the path through them, by sending a request into the environment with nothing listening. It takes what the global fetch takes and answers with a Response:

const http = new SimAwsHttp({ simAws });
const response = await http.fetch("https://www.example.test/docs/x?a=1", { redirect: "manual" });

// Then the apex redirect the CloudFront Function performs has been applied.
expect(response.status).toBe(301);
expect(response.headers.get("location")).toBe("https://example.test/docs/x?a=1");

A hostname simulated Route 53 answers for is requested by its own name, with no port to add and no localUrl(...) adapting (an https URL works with no certificate set up for it). That one request resolves the hostname, finds the Distribution its alias records point at, and runs the deployed CloudFront Function at viewer-request. The certificate, the Hosted Zone records, the Distribution’s aliases and the function are covered together, where a template assertion over the same stack passes with every Route 53 record missing.

Reach for serveSimAws when the request comes from outside the process (a browser, curl, an SDK client pointed at a local endpoint). Both go through the same routing and service code, and SimAwsHttp leaves parallel test files no port to collide over. See the serving docs for the API.

Match service errors by name

// Wrong. Passes in production, fails against the simulator.
if (error instanceof ResourceNotFoundException) { ... }

// Right.
if (error instanceof Error && error.name === "ResourceNotFoundException") { ... }

The SDK exports exception classes, which invites the instanceof check. It holds only while exactly one copy of the SDK package is in play, and two copies in the module graph, a bundler, or a simulator raising its own classes all stop it matching silently. Yulin’s errors carry the service’s real error names and SDK-shaped $metadata without being instances of the SDK classes. Fix it in production code, where a version skew between two @aws-sdk/client-* packages breaks instanceof too. name is what the wire carries, and is right in both places.

Expect refusals, and treat them as a feature

Yulin refuses a property it cannot simulate and never ignores one. Silently accepting something that changes real behaviour would turn a deploy-time failure into a production one. The cost is that one unsupported setting can make a whole stack unsimulatable, one property at a time. Enumerate every refusal in one pass. Strip properties in a throwaway transform until the template deploys, keeping the list, then raise them together upstream. Taking them one release at a time is one round trip per property, and you never learn how far away a working simulation is.

Not every gap is a refusal. Several services record a property they cannot model and carry on, reporting it as an ignored property on the stack and on the resource. Check that report before trusting a test that depends on the setting.

Raise gaps upstream, and weight false passes far above false refusals

Fix gaps on the Yulin repository at source. A local workaround has to be maintained in every project that hits the same gap.

The asymmetry matters more than the volume. A simulator staying silent about something costs little, leaving that behaviour uncovered where it already was. A simulator saying 200 where production says 403 is the opposite of what it is for. So report a false pass with what production does and what the simulation did, and a false refusal with the property and the template that carries it. Raise a gap costing nothing but convenience as well, once it is forcing structural duplication.

A workaround kept while the issue is open wants a comment naming that issue and a revisit when it closes. Re-read those claims on each upgrade. They are the ones nothing tests.

Share one simulation across the whole test suite

The recommended lifecycle is one SimAws, one deployment and one SimSdk interception layer for the tests that do not change simulated time. This should be most of the test suite. Do this in Vitest setup. Tests should treat the result as a long-running AWS account or LocalStack container whose state survives every test and test file.

An in-process simulation needs the test files to share a worker and module cache. Set fileParallelism: false and isolate: false, then load one setup module through setupFiles:

export default defineConfig({
  test: {
    fileParallelism: false,
    isolate: false,
    setupFiles: ["./test/yulin.setup.ts"],
  },
});

Keep the one-time work in an imported module. Vitest executes a setup file before each test file, even with isolation disabled, but imported modules stay cached in the shared worker.

const ready = (async () => {
  const simAws = new SimAws();
  const simSdk = new SimSdk({ simAws });

  simSdk.intercept(DynamoDBClient);
  simSdk.intercept(S3Client);

  const stack = await simAws.cloudFormation().deployTemplateFile({
    templatePath: "cdk.out/SiteStack.template.json",
  });
  await stack.waitForDeployComplete();

  return { simAws, simSdk, stack };
})();

export function yulinSuite() {
  return ready;
}

import { yulinSuite } from "./yulin-suite";

await yulinSuite();

Tests import yulinSuite() and work against that same state. Give every test data a random name or identifier, query by that identifier and never assume a service starts empty. A missing-resource case uses a new identifier that no test created. A count assertion records the relevant count before the action when it cannot query by identifier. Tests remain independent without clearing tables, buckets or queues between them.

const { simAws } = await yulinSuite();
const key = `uploads/${faker.string.uuid()}.png`;

// Exercise the application, then read this test's object from shared S3 state.
const object = await simAws.s3().getObject({ input: { Bucket: bucket, Key: key } });

Do not put the simulation in Vitest globalSetup. That hook runs outside the test workers and can only pass serializable values into them. setupFiles runs in the test worker and can share the live SimAws object through the cached module above.

This shared setup also shares the simulation clock. Keep tests that call advanceBy, resume the clock or otherwise change simulated time out of this group. Put them in a separate Vitest project or file pattern, such as *.clock.iso.test.ts, and give each test an isolated Yulin setup. The split keeps the common suite setup cheap while allowing the smaller clock-testing group to control time.

Creating Yulin once per test or once per file is supported. Reserve it for a case that deliberately tests an entire fresh account, an independent clock or incompatible interception. Use the shared setup by default. A beforeEach or file-level beforeAll that deploys the application again usually turns random test data into repeated infrastructure work.

Bind a handler and run it as a real simulated Lambda

bindings is how to run your own code inside the simulation, for an AWS::CloudFront::Function as much as for a Lambda function. Bind an in-process handler at deploy time, targeting a Lambda function by logicalId, functionName, arn, cdkPath or imageRepository, and a CloudFront Function by logicalId, functionName or arn. On a CloudFront Function it is what covers source cdk synth embedded or transformed.

await simAws.cloudFormation().deployTemplateFile({
  templatePath: "cdk.out/ApiStack.template.json",
  bindings: [{ logicalId: "UploadFunction", handler: uploadHandler }],
});

The handler still runs in process, closing over test state and stopping on a breakpoint. The difference from calling it directly is that a missing s3:PutObject on the execution role now fails the test, at the point AWS would have failed it.

Invoke through simulated Lambda

Binding a handler proves nothing about IAM on its own. The execution role, the function’s environment and its outbound HTTP are all applied by the invocation, and the test has to go through simAws.lambda().invoke(new InvokeCommand({ FunctionName, Payload })) to get any of them. A test holding the same handler reference and calling it directly runs it in the test’s own scope, as the test’s own caller, with none of the three.

To check a suite covers the policy, remove an action such as dynamodb:GetItem from the role in the CDK stack and re-synthesize. Invoked cases fail with an AccessDenied naming the execution role and the action. Cases calling the handler directly stay green.

Wire the object graph once, in production

The costliest shape a Yulin suite grows is a second wiring of the application’s own object graph, built so that a recorder can be injected into it and asserted on. Nothing needs it. bindings plus invoke run the real handler under its execution role, state reads back through the production reader against the deployed table, and accounts and other fixtures come from the simulation’s own accessors. A recording logger was the last reason standing, and from 1.17.1 a bound handler’s output is recorded into its log group, read back at /aws/lambda/<function name> through FilterLogEvents.

The console and the process standard streams are bridged for the length of an invocation, as process.env and Date are. A logging library building its own Console over those streams at module scope is recorded too, Powertools’ Logger included, both its JSON log line and its EMF metric document.

So when a test builds the application’s own graph, ask what it cannot get through an invocation. Expect the answer to be nothing.

Read the environment inside the handler

A bound handler gets the function’s declared environment variables with nothing stubbed. SimProcessEnvironment holds a run’s variables in an AsyncLocalStorage store and resolves process.env to it for the length of the run, with concurrent runs each seeing their own. What it cannot reach is a read that already happened. A handler module doing const TABLE = process.env.TABLE_NAME at module scope is evaluated when the test file imports it, long before any run, and captures the host value.

So read the environment inside the handler body, memoising there where a warm container should build its clients once. The substituted Date works the same way, and a vi.stubEnv around a bound handler is the sign of a handler reading too early. SimLambdaEnvironmentConflicts warns about this, but only where the host value and the declared value differ, and a suite that stubs the right values stays quiet and never learns.

Keep the zip path for a case about the artefact

Deploying a Lambda function without bindings runs the bundle cdk synth produced. deployTemplateFile publishes the cloud assembly’s assets into the staging bucket in simulated S3, and the modules are evaluated as CommonJS in a vm sandbox with its own process.env, Date and HTTP clients, where the module-scope problem above never arises. Both paths authorise through the execution role, and the same policy mutation fails a zip-path test exactly as it fails a bound one.

What that buys is the artefact that deploys, its imports and its bundling included, and a case about the bundle itself is the case to spend it on. Everywhere else it is the fallback. Every run waits on the build, a stale cdk.out runs yesterday’s handler, and the vm runtime loads CommonJS as the real nodejs runtimes do, leaving a NodejsFunction synthesized with format: OutputFormat.ESM refused at cold start.

Outbound HTTP is answered by the simulation

From 1.16.2, a simulated Lambda’s fetch and its node:http and node:https are answered by the simulation for every hostname simulated Route 53 resolves, through the same in-process entry point a request arriving on localhost uses. A Cognito user pool domain, an HTTP API and a load balancer are all answered without the test knowing which of them it asked, and everything else reaches the network as addressed. That is what makes an OAuth authorization code exchange testable, since it lives only at the pool domain’s hosted /oauth2/token endpoint with no SDK operation behind it, and it lets CognitoJwtVerifier fetch a simulated pool’s JWKS from inside a handler with no cache primed.