{"id":15471646,"url":"https://github.com/thadeu/jest-localstack-preset","last_synced_at":"2025-04-22T13:19:33.761Z","repository":{"id":47296357,"uuid":"515996616","full_name":"thadeu/jest-localstack-preset","owner":"thadeu","description":"🥾 A simple way to do testing AWS Services and Jest or Serverless and Jest","archived":false,"fork":false,"pushed_at":"2024-02-08T09:04:27.000Z","size":75,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T13:19:15.065Z","etag":null,"topics":["jest","jest-aws","jest-dynamodb","jest-serverless","localstack","serverless"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thadeu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-20T13:37:54.000Z","updated_at":"2023-07-25T14:47:31.000Z","dependencies_parsed_at":"2024-06-21T15:36:12.870Z","dependency_job_id":null,"html_url":"https://github.com/thadeu/jest-localstack-preset","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fjest-localstack-preset","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fjest-localstack-preset/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fjest-localstack-preset/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fjest-localstack-preset/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thadeu","download_url":"https://codeload.github.com/thadeu/jest-localstack-preset/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250246730,"owners_count":21398919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jest","jest-aws","jest-dynamodb","jest-serverless","localstack","serverless"],"created_at":"2024-10-02T02:21:06.549Z","updated_at":"2025-04-22T13:19:33.730Z","avatar_url":"https://github.com/thadeu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jest-localstack-preset\n\n🥾 A simple way to do testing AWS Services and Jest or Serverless and Jest\n\n[![ci](https://github.com/thadeu/jest-localstack-preset/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/thadeu/jest-localstack-preset/actions/workflows/ci.yml)\n[![Npm package version](https://badgen.net/npm/v/@thadeu/jest-localstack-preset)](https://www.npmjs.com/package/@thadeu/jest-localstack-preset)\n\n## Install\n\nInstall via yarn or npm\n\n```bash\n$ yarn add -D @thadeu/jest-localstack-preset\n```\n\nor\n\n```bash\n$ npm i -D @thadeu/jest-localstack-preset\n```\n\n## Dependencies\n\n- Docker\n- [LocalStack Image](https://docs.localstack.cloud/get-started/#starting-localstack-with-docker)\n- NodeJS \u003e= 12.x\n\n## Configuration\n\nConfigure `jest.config.js`, adding a custom `preset` and `setupFiles`\n\n```js\nmodule.exports = {\n  preset: '@thadeu/jest-localstack-preset',\n  setupFiles: ['./jest.setup.js'],\n  ...\n}\n```\n\nCreate `jest.localstack.js` file with your required services, for example.\n\n```js\nmodule.exports = {\n  services: ['dynamodb', 'kinesis', 's3', 'apigateway', 'lambda'],\n  showLog: false,\n  readyTimeout: 10000,\n  autoPullImage: true,\n  S3Buckets: [\n    {\n      Bucket: 'examplebucket',\n    },\n  ],\n  DynamoDB: [\n    {\n      TableName: `users_test`,\n      BillingMode: 'PAY_PER_REQUEST',\n      KeySchema: [\n        { AttributeName: 'pk', KeyType: 'HASH' },\n        { AttributeName: 'sk', KeyType: 'RANGE' },\n      ],\n      AttributeDefinitions: [\n        { AttributeName: 'pk', AttributeType: 'S' },\n        { AttributeName: 'sk', AttributeType: 'S' },\n      ],\n    },\n  ],\n}\n```\n\n| Key           | Value    | Description                                        |\n| ------------- | -------- | -------------------------------------------------- |\n| readyTimeout  | boolean  | Define timeout in milliseconds to create container |\n| autoPullImage | boolean  | Define if we go to download image automatically    |\n| showLog       | boolean  | Define show logs for localstack                    |\n| services      | [string] | List of AWS Services                               |\n\n\u003e You can define environment `JEST_LOCALSTACK_AUTO_PULLING` to precede autoPullImage configuration in your CI/CD\n\nCreate a file `jest.setup.js`\n\n```js\nconst AWS = require('aws-sdk')\n\nconst { configureMockSDK } = require('@thadeu/jest-localstack-preset/aws')\nconfigureMockSDK(AWS)\n```\n\n## Usage\n\nWhen you use `configureMockSDK` function, we configure many things to you transparently. This means that you going to use `aws-sdk` normally, without change.\n\n\u003e We will apply yhis\n\n```js\n{\n  accessKeyId: 'access-key',\n  secretAccessKey: 'secret-key',\n  region: 'us-east-1',\n  endpoint: 'http://localhost:4566',\n  s3ForcePathStyle: true,\n}\n```\n\nBut, if you need configure in runtime, enjoy and to do that. Anywhere you can use the `endpoint_url` to access localstack services locally.\n\nSo, use custom endpoint `process.env.AWS_ENDPOINT_URL` for general or specific to DynamoDB `process.env.AWS_DYNAMODB_ENDPOINT_URL` in the AWS clients in your code.\n\nFor example to use DynamoDB or S3.\n\n```js\nconst AWS = require('aws-sdk')\n\nconst Table = new AWS.DynamoDB.DocumentClient({\n  endpoint: process.env.AWS_DYNAMODB_ENDPOINT_URL,\n})\n```\n\nSo, create your tests using Jest.\n\nAn example for DynamoDB.\n\n```js\nconst AWS = require('aws-sdk')\n\nconst Table = new AWS.DynamoDB.DocumentClient({\n  endpoint: process.env.AWS_DYNAMODB_ENDPOINT_URL,\n})\n\nit('should insert item into table', async () =\u003e {\n  await Table.put({\n    TableName: 'users_test',\n    Item: { pk: '1', sk: 'jest-localstack-preset' },\n  }).promise()\n\n  const { Count } = await Table.scan({ TableName: 'users_test' }).promise()\n  expect(Count).toBe(1)\n})\n```\n\nAn example for S3\n\n```js\nconst AWS = require('aws-sdk')\n\nconst s3 = new AWS.S3({\n  endpoint: process.env.AWS_ENDPOINT_URL,\n  s3ForcePathStyle: true,\n})\n\nit('must be create a bucket', async () =\u003e {\n  await s3.createBucket({ Bucket: 'examplebucket' }).promise()\n\n  const { Buckets } = await s3.listBuckets().promise()\n\n  expect(Buckets.length).toBe(1)\n  expect(Buckets[0].Name).toBe('examplebucket')\n})\n```\n\nUsually you go to use other files, class and functions.\n\n```js\n// UserReposity.js\nconst AWS = require('aws-sdk')\n\n// =================================================\n// WITH configureMockSDK in your setupFiles\n// =================================================\nconst Table = new AWS.DynamoDB.DocumentClient()\n\n// =================================================\n// WITHOUT configureMockSDK\n// =================================================\n// const Table = new AWS.DynamoDB.DocumentClient({\n//   endpoint: process.env.AWS_DYNAMODB_ENDPOINT_URL,\n//   region: process.env.AWS_REGION,\n// })\n\nexport default class UserReposity {\n  static async all(props = {}) {\n    return Table.scan({ TableName: 'users', ...props }).promise()\n  }\n\n  static async save(props) {\n    return Table.put({\n      TableName: 'users',\n      ...props,\n    }).promise()\n  }\n}\n\n// UserReposity.test.js\nimport UserReposity from './UserReposity'\n\ndescribe('UserReposity', function() {\n  it('should insert item into repository', async () =\u003e {\n    await UserReposity.save({\n      Item: { pk: '1', sk: 'jest-localstack-preset' },\n    })\n\n    const { Count } = await UserReposity.all()\n    expect(Count).toBe(1)\n  })\n})\n```\n\nIn this moment, all process will be make using [LocalStack](https://github.com/localstack/localstack).\n\n## How Its Works?\n\nProgrammatically, we start a docker container with localstack, we run all tests and then, when tests finished, we destroy all containers related\n\n## What services work?\n\nBasically, whatever!\n\nFor more AWS Service available visit, https://docs.localstack.cloud/aws/feature-coverage/\n\n## Debugging\n\nYou can enabled debug flag using your custom environment.\n\n| Envs                         | Type    |\n| ---------------------------- | ------- |\n| LOCALSTACK_DEBUG             | boolean |\n| JEST_LOCALSTACK_AUTO_PULLING | boolean |\n\n## CI (Continuous Integration)\n\n- Github Actions, see [.github/workflows/ci](.github/workflows/ci.yml)\n\nSimple example\n\n```yml\nname: ci\n\non: push\n\njobs:\n  jest:\n    name: jest\n    runs-on: ubuntu-latest\n\n    services:\n      localstack:\n        image: localstack/localstack\n\n    defaults:\n      run:\n        working-directory: ./\n\n    steps:\n      - uses: actions/checkout@v2\n\n      - uses: actions/cache@v2\n        with:\n          path: '**/node_modules'\n          key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}\n          restore-keys: |\n            ${{ runner.os }}-modules-\n\n      - name: Setup NodeJS\n        uses: actions/setup-node@v2\n        with:\n          node-version: 14.17.x\n\n      - name: Install Yarn Dependencies\n        run: yarn install --frozen-lockfile\n\n      - name: Yarn Jest\n        run: yarn test\n        env:\n          LOCALSTACK_DEBUG: true\n          JEST_LOCALSTACK_AUTO_PULLING: true\n```\n\n## Disclaimer\n\nThis project is based on the amazing project https://github.com/goldsam/jest-localstack.\n\n## Contributing\n\nOnce you've made your great commits (include tests, please):\n\n1. Fork this repository\n2. Create a topic branch - git checkout -b my_branch\n3. Push to your branch - git push origin my_branch\n4. Create a pull request\n5. That's it!\n\nPlease respect the indentation rules and code style. And use 2 spaces, not tabs. And don't touch the version thing or distribution files; this will be made when a new version is going to be release\n\n## License\n\nThe Dockerfile and associated scripts and documentation in this project are released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthadeu%2Fjest-localstack-preset","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthadeu%2Fjest-localstack-preset","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthadeu%2Fjest-localstack-preset/lists"}