ACM
Yulin simulates AWS Certificate Manager in memory. Tests can request and inspect certificates, check DNS validation against simulated Route 53 and create certificates from CloudFormation templates.
Yulin local AWS simulator
Yulin is a local AWS simulator for testing Node.js applications. It simulates AWS system behaviour for fast, isolated testing, local development, and CI.
Installation
Section titled “Installation”Install Yulin as a development dependency:
npm i -D @kensio/yulinWhy use Yulin?
Section titled “Why use Yulin?”Yulin runs in the same single process as your tests and application under test. No network, containers, or external I/O are involved unless you explicitly choose to serve a simulation on localhost.
This isolated system approach makes it practical to test meaningful behaviour across AWS services without slow or fragile infrastructure setup.
- Tests run fast because state is in memory.
- Test setup is simple, with no containers or extra services to manage.
- Each
SimAwsinstance is cheap and encapsulated, so tests can create isolated AWS environments freely. - You can combine Yulin with other mocks and simulators, such as
nock. - You can test behaviour across multiple simulated AWS services in one process and step through the whole system in a debugger.
Direct interaction with simulated AWS
Section titled “Direct interaction with simulated AWS”Create a simulated AWS environment and interact with supported services directly:
import { SimAws } from "@kensio/yulin";import { CreateTableCommand } from "@aws-sdk/client-dynamodb";
const simAws = new SimAws();
// Default Account and Region.await simAws.service("dynamoDb").createTable( new CreateTableCommand({ TableName: "FoobarTable", KeySchema: [{ AttributeName: "id", KeyType: "HASH" }], }),);
// Specify Account.await simAws.account("111111111111").service("dynamoDb").createTable({ ... });
// Specify Region.await simAws.region("eu-west-2").service("dynamoDb").createTable({ ... });
// Specify Account and Region.await simAws.account("111111111111").region("eu-west-2").service("dynamoDb").createTable({ ... });AWS state is simulated internally, so you can test realistic interactions with multiple AWS services.
If you prefer, you can also instantiate simulated services individually:
import { SimS3 } from "@kensio/yulin/s3";import { CreateBucketCommand } from "@aws-sdk/client-s3";
const simS3 = new SimS3();
await simS3.createBucket(new CreateBucketCommand({ Bucket: "foo-bucket" }));That simulated service then has its own isolated state.
You can listen on a port to serve your simulated AWS on localhost:
import { SimAws } from "@kensio/yulin";import { serveSimAws } from "@kensio/yulin/serve";import { CreateBucketCommand, PutBucketWebsiteCommand, PutObjectCommand,} from "@aws-sdk/client-s3";
const simAws = new SimAws();const srv = await serveSimAws({ simAws }); // Chooses available port on localhost.
const simS3 = simAws.region("eu-west-2").s3();await simS3.createBucket(new CreateBucketCommand({ Bucket: "foo-site" }));await simS3.putBucketWebsite( new PutBucketWebsiteCommand({ Bucket: "foo-site", WebsiteConfiguration: { IndexDocument: { Suffix: "index.html", }, }, }),);await simS3.putObject( new PutObjectCommand({ Bucket: "foo-site", Key: "foo/index.html", Body: "<h1>Hello, world!</h1>", Metadata: { "content-type": "text/html; charset=utf-8", }, }),);
const bucketWebsiteUrl = srv.localUrl(simS3.getBucketWebsiteUrl("foo-site"));console.log(bucketWebsiteUrl.toString());
// Fetch /foo/index.html from the simulated S3 bucket website via port on localhost.const res = await fetch(new URL("/foo/", bucketWebsiteUrl));What’s in a name?
Section titled “What’s in a name?”The word yǔlín (雨林) means “rainforest” — a roundabout reference to “Amazon” as in Amazon Web Services.
Service documentation
Section titled “Service documentation”API Gateway HTTP APIs
Yulin simulates API Gateway HTTP APIs with routes, stages and Lambda proxy integrations. Application requests reach handlers running in the same Node.js process as the simulation.
API Gateway REST APIs
Yulin simulates API Gateway REST APIs with resources, methods, deployments and stages. Requests follow the API configuration and invoke simulated Lambda functions through proxy integrations.
Athena
Yulin simulates Athena queries against objects in simulated S3. Tests can declare query results or use an optional SQLite query engine, with Glue catalog lookups and results written to S3.
AWS Backup
Yulin simulates AWS Backup vaults, plans, selections, jobs and recovery points. Tests can manage backup resources through the AWS SDK and inspect the simulated state.
Bedrock
Yulin simulates Bedrock Runtime using response rules declared by the test. Application code sends model requests through the AWS SDK and receives the configured responses without calling a model.
CloudFormation
Yulin deploys CloudFormation templates and synthesized CDK assemblies into an in-memory AWS simulation. Tests use the resources declared by their infrastructure code and inspect the resulting state.
CloudFront
Yulin simulates CloudFront distributions, origins, caching and edge functions. Requests pass through the distribution configuration to simulated origins, with optional serving over localhost.
CloudWatch Logs
Yulin simulates CloudWatch Logs in memory. Applications write events to log groups and streams through the AWS SDK, and tests can read a stream or filter events across a group.
CloudWatch Metrics
Yulin simulates CloudWatch metrics and alarms in memory. Applications publish datapoints and read statistics through the AWS SDK. Alarms evaluate on simulated time and can notify simulated SNS topics.
Cognito IDP
Yulin simulates Cognito user pools, app clients, users and groups. Tests can exercise authentication, tokens, hosted domains and Lambda triggers within the simulated AWS environment.
DynamoDB
Yulin simulates DynamoDB tables, indexes, items, streams and TTL in memory. Application code reads and writes through the AWS SDK against the same simulated state that tests can inspect.
ECR
Yulin represents ECR images with in-process Lambda handlers. Tests register a handler against a repository and tag, then create a simulated container image Lambda function using that image URI.
ECS
Yulin simulates ECS clusters, task definitions, tasks and services in memory. Tasks run JavaScript or TypeScript handlers bound to container image URIs, with operations authorised by simulated IAM.
Elastic Load Balancing
Yulin simulates Application Load Balancers, target groups, listeners and routing rules. Requests follow the listener configuration to registered Lambda functions or simulated ECS services.
EventBridge
Yulin simulates EventBridge event buses, rules and targets in memory. Rules match published events or run on simulated schedules, delivering to simulated Lambda, SQS, SNS or ECS.
EventBridge Scheduler
Yulin simulates EventBridge Scheduler in memory. Schedules fire as simulated time advances and assume execution roles to invoke their targets. Simulated IAM authorises schedule management operations.
Glue
Yulin simulates Glue Data Catalog databases, tables and partitions in memory. Simulated Athena reads the catalog and evaluates partition projection when it runs queries against simulated S3.
IAM
Yulin simulates IAM users, roles, policies and authorisation decisions. Simulated services check requests against IAM, STS issues role sessions and CloudFormation creates IAM resources from templates.
Kinesis Data Firehose
Yulin simulates Firehose delivery streams. Streams accept records directly or read from simulated Kinesis, buffer them and write to simulated S3. Advancing the clock flushes buffers whose interval has elapsed.
Kinesis Data Streams
Yulin simulates Kinesis streams, shards, records and shard iterators in memory. Application code writes records and reads them through the AWS SDK during tests and local development.
KMS
Yulin simulates KMS with in-memory keys and cryptographic operations through Node.js crypto. Symmetric keys use AES-256 and asymmetric keys use key pairs. Decryption checks the key and encryption context.
Lambda
Yulin runs Lambda functions in the test process from bound handlers, zip archives or code in simulated S3. Handlers run as their execution role, and simulated IAM authorises their AWS calls.
Organizations
Yulin simulates AWS Organizations structure and service control policies. Policies attached to roots, organizational units and accounts limit the permissions that simulated IAM grants to requests.
Personalize
Yulin simulates Personalize resources and recommendation APIs. Tests declare the recommendations a campaign or recommender returns. Resources become active immediately, without training a model.
Rekognition
Yulin simulates Rekognition with results declared for an image name or content hash. Tests configure labels, moderation results, faces and matches. SDK calls return those results without analysing images.
Route53
Yulin simulates Route 53 hosted zones, DNS records and DNSSEC configuration. Records can route local hostnames to simulated services, including CloudFront distributions and S3 bucket websites.
S3
Yulin simulates S3 buckets, objects, policies, notifications and website hosting in memory. Tests use the S3 API against simulated state, with optional localhost endpoints for API and website requests.
Secrets Manager
Yulin simulates Secrets Manager with encrypted secret versions and staging labels. Simulated KMS encrypts and decrypts each version, and simulated IAM authorises operations.
SES
Yulin simulates SES v2 email identities, templates, sandbox rules and suppression rules. Accepted messages are recorded for tests to inspect, including recipients, subject, body and attachments. No email is delivered.
SNS
Yulin simulates SNS standard topics and subscriptions in memory. Published messages can reach simulated SQS queues, invoke Lambda functions or create SMS records for tests to inspect.
SQS
Yulin simulates SQS standard queues in memory. Tests send and receive messages, advance visibility timeouts with the simulation clock and redrive messages to dead-letter queues. Simulated IAM authorises operations.
SSM Parameter Store
Yulin simulates SSM Parameter Store in memory. Applications create, read, update and delete parameters through the AWS SDK. Each write creates a version, and simulated IAM authorises operations.
Step Functions
Yulin runs Step Functions state machines in the test process. Amazon States Language tasks invoke simulated services, waits and retries use the simulation clock, and tests can inspect execution history.
STS
Yulin simulates STS AssumeRole and GetCallerIdentity. Tests can obtain temporary role credentials, exercise role chains and ExternalId checks, and inspect caller identity against simulated IAM.
WAFv2
Yulin simulates WAFv2 web ACLs, IP sets and regex pattern sets. Tests can evaluate a request directly or protect simulated API Gateway REST APIs, Cognito user pools and CloudFront distributions.