{"id":15471813,"url":"https://github.com/thadeu/vitest-localstack","last_synced_at":"2025-04-06T01:42:39.662Z","repository":{"id":205890574,"uuid":"715402350","full_name":"thadeu/vitest-localstack","owner":"thadeu","description":"🥾 A simple way to do testing AWS Services using Vitest","archived":false,"fork":false,"pushed_at":"2023-12-12T14:12:52.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-15T09:09:58.966Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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":"2023-11-07T04:13:33.000Z","updated_at":"2023-11-07T04:24:29.000Z","dependencies_parsed_at":"2023-12-12T15:41:52.981Z","dependency_job_id":null,"html_url":"https://github.com/thadeu/vitest-localstack","commit_stats":{"total_commits":8,"total_committers":1,"mean_commits":8.0,"dds":0.0,"last_synced_commit":"61437f2836e64eea22ac34e4572da537e4be4cb5"},"previous_names":["thadeu/vitest-localstack"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fvitest-localstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fvitest-localstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fvitest-localstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thadeu%2Fvitest-localstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thadeu","download_url":"https://codeload.github.com/thadeu/vitest-localstack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423494,"owners_count":20936622,"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":[],"created_at":"2024-10-02T02:21:50.549Z","updated_at":"2025-04-06T01:42:39.636Z","avatar_url":"https://github.com/thadeu.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vitest-localstack\n\n🥾 A simple way to do testing AWS Services using Vitest\n\n[![ci](https://github.com/thadeu/vitest-localstack/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/thadeu/vitest-localstack/actions/workflows/ci.yml)\n[![Npm package version](https://badgen.net/npm/v/@thadeu/vitest-localstack)](https://www.npmjs.com/package/@thadeu/vitest-localstack)\n\n## Install\n\nInstall via yarn or npm\n\n```bash\n$ yarn add -D @thadeu/vitest-localstack\n```\n\nor\n\n```bash\n$ npm i -D @thadeu/vitest-localstack\n```\n\nor directly via Github\n\n```bash\n$ npm i -D thadeu/vitest-localstack\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\nIn your `vite.config.ts`, adding into test object, a globalSetup using `vite.setup.ts`\n\n```js\nimport { defineConfig } from 'vitest/config'\n\nexport default ({ mode }) =\u003e {\n  return defineConfig({\n    test: {\n      globalSetup: ['./vite.setup.ts'],\n    },\n  })\n}\n```\n\nCreate or update your `vite.setup.ts`\n\n```ts\nimport localStackSetup from '@thadeu/vitest-localstack/setup'\nimport localStackTeardown from '@thadeu/vitest-localstack/teardown'\n\nexport async function setup() {\n  await localStackSetup()\n}\n\nexport async function teardown() {\n  await localStackTeardown()\n}\n\n```\n\nCreate or update your `localstack.config.js` file with your required services, for example.\n\n```js\nmodule.exports = {\n  // https://docs.localstack.cloud/aws/feature-coverage/\n  services: ['dynamodb', 'kinesis', 's3'],\n  showLog: JSON.parse(process.env.LOCALSTACK_DEBUG || false),\n  autoPullImage: true,\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 `VITEST_LOCALSTACK_AUTO_PULLING` to precede autoPullImage configuration in your CI/CD\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```ts\nimport AWS from 'aws-sdk'\n\nconst Table = new AWS.DynamoDB.DocumentClient({\n  endpoint: process.env.AWS_DYNAMODB_ENDPOINT_URL,\n})\n```\n\nSo, create your tests and then.\n\nAn example for DynamoDB.\n\n```ts\nimport AWS from 'aws-sdk'\nimport { describe, it, expect } from 'vitest'\n\nimport { configureMockSDK } from '@thadeu/vitest-localstack'\nconfigureMockSDK(AWS)\n\nconst Table = new AWS.DynamoDB.DocumentClient()\n\nit('should insert item into table', async () =\u003e {\n  await Table.put({\n    TableName: 'users_test',\n    Item: { pk: '1', sk: 'vitest-localstack' },\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```ts\nimport AWS from 'aws-sdk'\nimport { describe, it, expect } from 'vitest'\n\nimport { configureMockSDK } from '@thadeu/vitest-localstack'\nconfigureMockSDK(AWS)\n\nconst s3 = new AWS.S3()\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```\n\nUsually you go to use other files, class and functions.\n\n```ts\n// UserReposity.js\nimport AWS from 'aws-sdk'\nconst Table = new AWS.DynamoDB.DocumentClient()\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.ts\nimport AWS from 'aws-sdk'\nimport { describe, it, expect } from 'vitest'\n\nimport { configureMockSDK } from '@thadeu/vitest-localstack'\nconfigureMockSDK(AWS)\n\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: 'vitest-localstack' },\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| VITEST_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  test:\n    name: test\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: 18.17\n\n      - name: Install Yarn Dependencies\n        run: yarn install --frozen-lockfile\n\n      - name: Yarn tests\n        run: yarn test\n        env:\n          LOCALSTACK_DEBUG: true\n          VITEST_LOCALSTACK_AUTO_PULLING: true\n```\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%2Fvitest-localstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthadeu%2Fvitest-localstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthadeu%2Fvitest-localstack/lists"}