Merge branch 'main' into protected-methods

zirkelc · Nov 29, 2024 · 84d505a · 84d505a
2 parents 42d7708 + 32baa49
commit 84d505a
Show file tree

Hide file tree

Showing 37 changed files with 1,625 additions and 4,434 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -15,7 +15,6 @@
     // Add the ids of extensions you want installed when the container is created.
     "extensions": [
       "biomejs.biome",
-      "firsttris.vscode-jest-runner",
       "vitest.explorer"
     ],
     "vscode": {

diff --git a/.github/boring-cyborg.yml b/.github/boring-cyborg.yml
@@ -40,35 +40,24 @@ labelPRBasedOnFilePath:
   tests:
     - packages/logger/tests/*
     - packages/logger/tests/**/*
-    - packages/logger/jest.config.cjs
     - packages/tracer/tests/*
     - packages/tracer/tests/**/*
-    - packages/tracer/jest.config.cjs
     - packages/metrics/tests/*
     - packages/metrics/tests/**/*
-    - packages/metrics/jest.config.cjs
     - packages/idempotency/tests/*
     - packages/idempotency/tests/**/*
-    - packages/idempotency/jest.config.cjs
     - packages/parameters/tests/*
     - packages/parameters/tests/**/*
-    - packages/parameters/jest.config.cjs
     - packages/parser/tests/*
     - packages/parser/tests/**/*
-    - packages/parser/jest.config.cjs
     - packages/event-handler/tests/*
     - packages/event-handler/tests/**/*
-    - packages/event-handler/jest.config.cjs
     - packages/validator/tests/*
     - packages/validator/tests/**/*
-    - packages/validator/jest.config.cjs
     - packages/batch/tests/*
     - packages/batch/tests/**/*
-    - packages/batch/jest.config.cjs
     - packages/commons/tests/*
     - packages/commons/tests/**/*
-    - packages/commons/jest.config.cjs
-    - layers/jest.config.cjs
     - layers/tests/*
     - layers/tests/**/*
 

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -41,13 +41,18 @@ updates:
         - "@aws-sdk/*"
         - "@smithy/*"
         - "aws-sdk-client-mock"
-        - "aws-sdk-client-mock-jest"
+        - "aws-sdk-client-mock-vitest"
       aws-cdk:
         patterns:
         - "@aws-cdk/cli-lib-alpha"
         - "aws-cdk-lib"
         - "aws-cdk"
-      typedoc:
+      typescript:
         patterns:
         - "typedoc"
-        - "typedoc-plugin-*"
+        - "typedoc-plugin-*"
+        - "typescript"
+      vitest:
+        patterns:
+        - "vitest"
+        - "@vitest/*"
diff --git a/.github/workflows/quality_check.yml b/.github/workflows/quality_check.yml
@@ -0,0 +1,128 @@
+name: Code quality
+
+# USAGE
+#
+# Automatically triggered when a PR is added to the merge queue.
+
+on:
+  merge_group:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  code-quality:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: dev
+    strategy:
+      matrix:
+        version: [18, 20, 22]
+        workspace: [
+          "packages/batch",
+          "packages/commons",
+          "packages/event-handler",
+          "packages/idempotency",
+          "packages/jmespath",
+          "packages/logger",
+          "packages/tracer",
+          "packages/parser",
+          "packages/parameters",
+          "packages/metrics"
+        ]
+      fail-fast: false
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Setup NodeJS
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: ${{ matrix.version }}
+          cache: "npm"
+      - name: Setup dependencies
+        uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
+        with:
+          nodeVersion: ${{ matrix.version }}
+      - name: Linting
+        run: npm run lint -w ${{ matrix.workspace }}
+      - name: Unit tests
+        run: |
+          npm run test:unit:coverage -w ${{ matrix.workspace }}
+          npm run test:unit:types -w ${{ matrix.workspace }}
+  check-examples:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: dev
+    strategy:
+      matrix:
+        example: ["app"]
+      fail-fast: false
+    defaults:
+      run:
+        working-directory: examples/${{ matrix.example }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Setup NodeJS
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 22
+          cache: "npm"
+      - name: Setup dependencies
+        uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
+      - name: Run linting
+        run: npm run lint
+      - name: Run tests
+        run: npm t
+  check-layer-publisher:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: dev
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Setup NodeJS
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 22
+          cache: "npm"
+      - name: Setup dependencies
+        uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
+      - name: Run linting
+        run: npm run lint -w layers
+      - name: Run tests
+        run: npm run test:unit -w layers
+  check-docs-snippets:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: dev
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Setup NodeJS
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 22
+          cache: "npm"
+      - name: Setup dependencies
+        uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
+      - name: Run linting
+        run: npm run lint -w examples/snippets
+  check-docs:
+    runs-on: ubuntu-latest
+    env:
+      NODE_ENV: dev
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Setup NodeJS
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: 22
+          cache: "npm"
+      - name: Setup dependencies
+        uses: aws-powertools/actions/.github/actions/cached-node-modules@d406bac5563f1d8c793519a3eedfe620f6a14872
+      - name: Run linting
+        run: npm run lint:markdown
diff --git a/.npmignore b/.npmignore
@@ -12,7 +12,8 @@ coverage
 tslint.json
 tsconfig.json
 MakeFile
-jest.config.cjs
+vitest.config.ts
+vitest.workspace.ts
 .npmignore
 .eslintignore
 .huskyrc.js

diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md
@@ -13,17 +13,7 @@ Tests are defined alongside the code they test, and can be found under the `test
 
 Each test type has its own folder, and each test file is named after the feature it tests. For example, the tests for the `@aws-lambda-powertools/logger` module can be found under `packages/logger/tests/unit` and `packages/logger/tests/e2e`.
 
-Tests are written using [Jest](https://jestjs.io) and are grouped into categories. You can run each group separately or all together thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups).
-
-Each test file needs to be tagged with the proper group, otherwise, it won't be executed. The group is defined in the header of the file, and it follows this convention:
-
-```typescript
-/**
- * Tests metrics
- *
- * @group unit/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
- */
-```
+Tests use [Vitest](http://vitest.dev) as test runner and are grouped by packages and type. You can run each group separately or all together by passing extra arguments to the test command.
 
 The test file should contain one or more tests organized using the `describe` and `it` functions. Each test should be named after the feature it tests, and should be as descriptive as possible. For example, the test for the `Logger` class `info` method is named `should log info message`.
 
@@ -67,7 +57,6 @@ To run unit tests, you can use of the following commands from the root folder:
 * `npm test -ws` to run all the unit tests for all the modules sequentially
 * `npm run test:parallel` to run all the unit tests for all the modules in parallel
 * `npm test -w packages/metrics` to run all the unit tests for the `metrics` module
-* `npm run jest -w packages/metrics -- --group=unit/metrics/middleware` to run all the unit tests for the `metrics` module that are tagged with the `unit/metrics/middleware` group
 
 We enforce 100% code coverage for unit tests. The test command will fail if the coverage is not 100% both on your local machine and in CI.
 
@@ -93,12 +82,12 @@ Below is a diagram that shows the flow of the integration tests:
 
 ```mermaid
 sequenceDiagram
-    Dev Environment / CI->>+Jest: npm run test:e2e
-    Jest-->Jest: Synthetize CloudFormation Stack
-    Jest->>+AWS: Deploy Stack
-    Jest->>+AWS: Invoke Lambda function
-    AWS->>Jest: Report logs / results
-    Jest-->Jest: Assert logs/result
-    Jest->>+AWS: Destroy Stack
-    Jest->>+Dev Environment / CI: show test results
+    Dev Environment / CI->>+Vitest: npm run test:e2e
+    Vitest-->Vitest: Synthetize CloudFormation Stack
+    Vitest->>+AWS: Deploy Stack
+    Vitest->>+AWS: Invoke Lambda function
+    AWS->>Vitest: Report logs / results
+    Vitest-->Vitest: Assert logs/result
+    Vitest->>+AWS: Destroy Stack
+    Vitest->>+Dev Environment / CI: show test results
 ```
diff --git a/docs/core/logger.md b/docs/core/logger.md
@@ -828,18 +828,20 @@ When you extend the default JSON serializer, we will call your custom serializer
 
 When unit testing your code that makes use of `logger.addContext()` or `injectLambdaContext` middleware and decorator, you can optionally pass a dummy Lambda Context if you want your logs to contain this information.
 
-This is a Jest sample that provides the minimum information necessary for Logger to inject context data:
+This is a sample that provides the minimum information necessary for Logger to inject context data:
 
 === "handler.test.ts"
 
     ```typescript
     --8<-- "examples/snippets/logger/unitTesting.ts"
     ```
 
-### Suppress logs with Jest
+### Suppress logs
 
-When unit testing your code with [Jest](https://jestjs.io) you can use the `POWERTOOLS_DEV` environment variable in conjunction with the Jest `--silent` CLI option to suppress logs from Logger.
+When unit testing your code with [Jest](https://jestjs.io) or [Vitest](http://vitest.dev) you can use the `POWERTOOLS_DEV` environment variable in conjunction with the `--silent` CLI option to suppress logs from Logger.
 
-```bash title="Disabling logs while testing with Jest"
-export POWERTOOLS_DEV=true && npx jest --silent
+```bash title="Disabling logs while testing with Vitest"
+export POWERTOOLS_DEV=true && npx vitest --silent
 ```
+
+Alternatively, you can also set the `POWERTOOLS_DEV` environment variable to `true` in your test setup file, or in a hoisted block at the top of your test file.
diff --git a/docs/core/metrics.md b/docs/core/metrics.md
@@ -473,20 +473,11 @@ To make it easier to test your code, you can set the `POWERTOOLS_DEV` environmen
 
 This allows you to spy on the logs emitted by the utility and assert that the metrics are being emitted correctly.
 
-```typescript title="Spying on emitted metrics"
-describe('Metrics tests', () => {
-  beforeAll(() => {
-    process.env.POWERTOOLS_DEV = 'true';
-  })
-
-  it('function metrics properly', async () => {
-    // Prepare
-    const metricsSpy = jest.spyOn(console, 'log').mockImplementation();
-
-    // Act & Assess
-  });
-});
-```
+=== "Spying on emitted metrics"
+
+    ```typescript hl_lines="4 10"
+    --8<-- "examples/snippets/metrics/testingMetrics.ts"
+    ```
 
 When running your tests with both [Jest](https://jestjs.io) and [Vitest](http://vitest.dev), you can use the `--silent` flag to silence the logs emitted by the utility.
 

diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md
@@ -832,21 +832,21 @@ The idempotency utility provides several routes to test your code.
 
 ### Disabling the idempotency utility
 
-When testing your code, you may wish to disable the idempotency logic altogether and focus on testing your business logic. To do this, you can set the environment variable POWERTOOLS_IDEMPOTENCY_DISABLED with a truthy value.
+When testing your code, you may wish to disable the idempotency logic altogether and focus on testing your business logic. To do this, you can set the environment variable `POWERTOOLS_IDEMPOTENCY_DISABLED` with a truthy value.
 
 ### Testing with local DynamoDB
 
 When testing your Lambda function locally, you can use a local DynamoDB instance to test the idempotency feature. You can use [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.DownloadingAndRunning.html) or [LocalStack](https://localstack.cloud/){target="_blank"}.
 
 === "handler.test.ts"
 
-    ```typescript hl_lines="7-9"
+    ```typescript hl_lines="18"
     --8<-- "examples/snippets/idempotency/workingWithLocalDynamoDB.test.ts"
     ```
 
 === "handler.ts"
 
-    ```typescript hl_lines="7-9"
+    ```typescript
     --8<-- "examples/snippets/idempotency/workingWithLocalDynamoDB.ts"
     ```
 

diff --git a/docs/utilities/parameters.md b/docs/utilities/parameters.md
@@ -450,11 +450,11 @@ The **`clientConfig`** parameter enables you to pass in a custom [config object]
 
 ### Mocking parameter values
 
-For unit testing your applications, you can mock the calls to the parameters utility to avoid calling AWS APIs. This can be achieved in a number of ways - in this example, we use [Jest mock functions](https://jestjs.io/docs/es6-class-mocks#the-4-ways-to-create-an-es6-class-mock) to patch the `getParameters` function.
+For unit testing your applications, you can mock the calls to the parameters utility to avoid calling AWS APIs. This can be achieved in a number of ways - in this example, we mock the module import to patch the `getParameters` function.
 
 === "handler.test.ts"
-	```typescript hl_lines="2 4-9 13 18"
-	--8<-- "examples/snippets/parameters/testingYourCodeFunctionsJestMock.ts"
+	```typescript hl_lines="4-6 12 22"
+	--8<-- "examples/snippets/parameters/testingYourCodeFunctionsMock.ts"
 	```
 
 === "handler.ts"
@@ -464,23 +464,23 @@ For unit testing your applications, you can mock the calls to the parameters uti
 
 With this pattern in place, you can customize the return values of the mocked function to test different scenarios without calling AWS APIs.
 
-A similar pattern can be applied also to any of the built-in provider classes - in this other example, we use [Jest spyOn method](https://jestjs.io/docs/es6-class-mocks#mocking-a-specific-method-of-a-class) to patch the `get` function of the `AppConfigProvider` class. This is useful also when you want to test that the correct arguments are being passed to the Parameters utility.
+A similar pattern can be applied also to any of the built-in provider classes - in this other example, we use spies to patch the `get` function of the `AppConfigProvider` class. This is useful also when you want to test that the correct arguments are being passed to the Parameters utility.
 
 === "handler.test.ts"
-	```typescript hl_lines="2 5 8 19 26-27"
-	--8<-- "examples/snippets/parameters/testingYourCodeProvidersJestMock.ts"
+	```typescript hl_lines="2 7 21-23"
+	--8<-- "examples/snippets/parameters/testingYourCodeProvidersMock.ts"
 	```
 
 === "handler.ts"
 	```typescript
 	--8<-- "examples/snippets/parameters/testingYourCodeProvidersHandler.ts"
 	```
 
-For when you want to mock the AWS SDK v3 client directly, we recommend using the [`aws-sdk-client-mock`](https://www.npmjs.com/package/aws-sdk-client-mock) and [`aws-sdk-client-mock-jest`](https://www.npmjs.com/package/aws-sdk-client-mock-jest) libraries. This is useful when you want to test how your code behaves when the AWS SDK v3 client throws an error or a specific response.
+For when you want to mock the AWS SDK v3 client directly, we recommend using the [`aws-sdk-client-mock`](https://www.npmjs.com/package/aws-sdk-client-mock) and [`aws-sdk-client-mock-vitest`](https://www.npmjs.com/package/aws-sdk-client-mock-vitest) libraries. This is useful when you want to test how your code behaves when the AWS SDK v3 client throws an error or a specific response.
 
 === "handler.test.ts"
-	```typescript hl_lines="2-8 11 14 18 23-30"
-	--8<-- "examples/snippets/parameters/testingYourCodeClientJestMock.ts"
+	```typescript hl_lines="2-7 12 16 21-28"
+	--8<-- "examples/snippets/parameters/testingYourCodeClientMock.ts"
 	```
 
 === "handler.ts"
@@ -495,6 +495,6 @@ Parameters utility caches all parameter values for performance and cost reasons.
 Within your tests, you can use `clearCache` method available in [every provider](#built-in-provider-class). When using multiple providers or higher level functions like `getParameter`, use the `clearCaches` standalone function to clear cache globally.
 
 === "handler.test.ts"
-	```typescript hl_lines="1 9"
+	```typescript hl_lines="1 6"
 	--8<-- "examples/snippets/parameters/testingYourCodeClearCache.ts"
 	```
diff --git a/examples/app/.gitignore b/examples/app/.gitignore
@@ -1,6 +1,6 @@
 *.js
 !.eslintrc.js
-!jest.config.js
+!vitest.config.js
 *.d.ts
 node_modules