# Yulin

> Yulin is a local AWS simulator for testing Node.js applications. It runs in the same process as the tests, with no containers, network or external I/O, so behaviour spanning several AWS services can be tested and stepped through in a debugger. It is an npm package, @kensio/yulin.

Each link below is the plain markdown of one page. Drop the `llms.txt` from a link for the page itself: https://yulinsim.dev/sdk/llms.txt is https://yulinsim.dev/sdk/ as HTML.

## Guides

- [Simulated AWS SDK](https://yulinsim.dev/sdk/llms.txt): Yulin can intercept AWS SDK clients and route their Commands to simulated AWS services.
- [Linting CloudFront Functions JS2](https://yulinsim.dev/lint/llms.txt): CloudFront Functions run JS2, which is ECMAScript 5.1 plus a named subset of ES 6 to 12 rather than a current JavaScript engine.
- [Serving simulated AWS on localhost](https://yulinsim.dev/serve/llms.txt): Serving puts a simulated AWS environment behind a real port, so a browser, curl or an SDK client reaches it over HTTP.
- [Simulated time](https://yulinsim.dev/time/llms.txt): Every timestamp a simulated AWS service produces comes from that simulation's own clock, and that clock can be moved.

## Simulated services

- [Simulated ACM](https://yulinsim.dev/services/acm/llms.txt): Yulin includes a simulated AWS Certificate Manager (ACM) service for tests and local development.
- [Simulated API Gateway HTTP APIs](https://yulinsim.dev/services/apigatewayv2/llms.txt): Yulin includes a simulated API Gateway v2 service, reachable as simAws.apiGatewayV2().
- [Simulated CloudFormation](https://yulinsim.dev/services/cloudformation/llms.txt): Yulin includes a simulated CloudFormation service for tests and local development.
- [Simulated CloudFront](https://yulinsim.dev/services/cloudfront/llms.txt): Yulin includes a simulated CloudFront service for tests and local development.
- [Simulated Cognito](https://yulinsim.dev/services/cognito/llms.txt): Yulin includes a simulated Cognito user pool directory for tests and local development.
- [Simulated DynamoDB](https://yulinsim.dev/services/dynamodb/llms.txt): Yulin includes a simulated DynamoDB for tests and local development. Tables are held in memory, and every operation is authorized by simulated IAM.
- [Simulated IAM](https://yulinsim.dev/services/iam/llms.txt): Yulin includes a simulated IAM service for tests and local development.
- [Simulated KMS](https://yulinsim.dev/services/kms/llms.txt): Yulin includes a simulated AWS Key Management Service (KMS) for tests and local development.
- [Simulated Lambda](https://yulinsim.dev/services/lambda/llms.txt): Yulin includes a simulated AWS Lambda service for tests and local development.
- [Simulated Rekognition](https://yulinsim.dev/services/rekognition/llms.txt): Simulated Rekognition answers detection calls from results declared against images, so a test can say which image fails moderation or holds a dog without any...
- [Simulated Route53](https://yulinsim.dev/services/route53/llms.txt): Yulin includes a simulated Route53 service for tests and local development.
- [Simulated S3](https://yulinsim.dev/services/s3/llms.txt): Yulin includes a simulated S3 service for tests and local development.
- [Simulated Secrets Manager](https://yulinsim.dev/services/secretsmanager/llms.txt): Yulin includes a simulated AWS Secrets Manager for tests and local development.
- [Simulated SNS](https://yulinsim.dev/services/sns/llms.txt): Yulin includes a simulated Amazon SNS for tests and local development. Topics are held in memory and every operation is authorized by simulated IAM.
- [Simulated SQS](https://yulinsim.dev/services/sqs/llms.txt): Yulin includes a simulated Amazon SQS for tests and local development.
- [Simulated SSM Parameter Store](https://yulinsim.dev/services/ssm/llms.txt): Yulin includes a simulated AWS Systems Manager Parameter Store for tests and local development.
- [Simulated STS](https://yulinsim.dev/services/sts/llms.txt): Yulin includes a simulated STS (Security Token Service) for tests and local development.

## Optional

- [npm package](https://www.npmjs.com/package/@kensio/yulin): install and version history
- [Source repository](https://github.com/KensioSoftware/yulin): source, issues and the docs these pages are built from

---

# Yulin local AWS simulator

Source: https://yulinsim.dev/

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

Install Yulin as a development dependency:

```bash
npm i -D @kensio/yulin
```

## 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 `SimAws` instance 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

Create a simulated AWS environment and interact with supported services directly:

```typescript
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:

```typescript
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:

```typescript
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?

The word yǔlín (雨林) means “rainforest” — a roundabout reference to “Amazon” as in Amazon Web
Services.

## Service documentation