aws-powertools · flochaz · Jan 14, 2022 · Jan 6, 2022 · Jan 6, 2022 · Jan 6, 2022
diff --git a/.github/workflows/on-merge-to-main.yml b/.github/workflows/on-merge-to-main.yml
@@ -7,7 +7,6 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
-
     steps:
     - name: "Checkout"
       uses: actions/checkout@v2

diff --git a/.github/workflows/run-e2e-tests.yml b/.github/workflows/run-e2e-tests.yml
@@ -0,0 +1,30 @@
+name: run-e2e-tests
+on:
+  workflow_dispatch: {}
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # needed to interact with GitHub's OIDC Token endpoint.
+      contents: read
+    steps:
+    - name: "Checkout"
+      uses: actions/checkout@v2
+    #########################    
+    # Release new version
+    #########################
+    - name: "Use NodeJS 14"
+      uses: actions/setup-node@v2
+      with:
+        node-version: '14'
+    - name: Install packages
+      run: |
+        npm ci
+        npm run lerna-ci
+    - name: Configure AWS credentials
+      uses: aws-actions/[email protected]
+      with:
+        role-to-assume: ${{ secrets.AWS_ROLE_ARN_TO_ASSUME }}
+        aws-region: eu-west-1
+    - name: Run integration tests
+      run: npm run lerna-test:e2e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -57,6 +57,96 @@ You can build and start a local docs website by running these two commands.
   - `npm run docs-buildDockerImage` OR `docker build -t squidfunk/mkdocs-material ./docs/`
   - `npm run docs-runLocalDocker` OR `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`
 
+### Tests
+
+Tests are under `tests` folder of each modules and split into two categories: unit tests and e2e (end-to-end) tests.
+
+You can run each group separately or all together thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups).
+
+Unit tests, under `tests/unit` folder are standard [Jest](https://jestjs.io) tests.
+
+End-to-end tests, under `tests/e2e` folder, will test the module features by deploying AWS Lambda functions into your AWS Account. We use [aws-cdk](https://docs.aws.amazon.com/cdk/v1/guide/getting_started.html) v1 library (not v2 due to [this cdk issue](https://github.com/aws/aws-cdk/issues/18211)) for Typescript for creating infrastructure, and [aws-sdk-js v2](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/) for invoking the functions and assert on the expected behaviors. All steps are also executed by Jest.
+
+
+Running end-to-end tests will deploy AWS resources. You will need an AWS account and the tests might incur costs. The cost from **some services** are covered by the [AWS Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) but not all of them. If you don't have an AWS Account follow [these instructions to create one](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
+
+When contributing to this repository, these end-to-end tests are run by the maintainers before merging a PR.
+
+
+**Unit tests**
+
+**Write**
+
+As mentioned before, tests are split into groups thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups) and therefore each test needs to be tagged properly by adding the following comments in the header of your unit test file:
+
+```typescript
+/**
+ * Tests metrics
+ *
+ * @group unit/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
+ */
+```
+
+**Run**
+
+To run unit tests you can either use 
+* npm task `lerna-test:unit` (`npm run lerna-test:unit`) in root folder to run them all
+* npm task `test:e2e` (`npm run test:unit`) in module folder (for example: `packages/metrics`) to run the module specific one
+* jest directly `npx jest --group=unit` in module folder to run the module specific one (You can run selective tests by restricting the group to the one you want. For instance `npx jest --group=unit/metrics/class`)
+
+**e2e tests**
+
+**Write**
+
+As mentioned in the previous section, tests are split into groups thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups) and therefore each test needs to be tagged properly by adding the following comments in the header of your unit test file:
+
+```typescript
+/**
+ * Tests data lake catalog
+ *
+ * @group e2e/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
+ */
+```
+
+ See `metrics/tests/e2e/decorator.test.ts` as an example.
+
+
+**Run**
+
+To run e2e tests you can either use 
+*  npm task `lerna-test:e2e` (`npm run lerna-test:e2e`) in root folder
+* npm task `test:e2e` (`npm run test:e2e`) in module folder (for example: `packages/metrics`) to run the module specific one
+* jest directly `npx jest --group=e2e` in module folder. (You can run selective tests by restricting the group to the one you want. For instance `npx jest --group=e2e/metrics/decorator`)
+
+Two important env variable can be used:
+* `AWS_PROFILE` to use the right AWS credentials
+* `DISABLE_TEARDOWN` if you don't want your stack to be destroyed at the end of the test (useful in dev mode when iterating over your code).
+
+Example: `DISABLE_TEARDOWN=true AWS_PROFILE=dev-account npx jest --group=e2e/metrics/decorator`
+
+**Automate**
+
+You can run the end-to-end tests automatically on your forked project by following these steps:
+1. Create an IAM role in your target AWS account, with the least amount of privilege.
+
+    As mentioned above in this page, we are leveraging CDK to deploy and consequently clean-up resources on AWS. Therefore to run those tests through Github actions you will need to grant specific permissions to your workflow.  
+
+    We recommend following [Amazon IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) for the AWS credentials used in GitHub Actions workflows, including:
+    * Do not store credentials in your repository's code.
+    * [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to the credentials used in GitHub Actions workflows.  Grant only the permissions required to perform the actions in your GitHub Actions workflows.
+    * [Monitor the activity](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#keep-a-log) of the credentials used in GitHub Actions workflows.
+
+    For an example of how to create a role in CDK, you can look at [@pahud/cdk-github-oidc](https://constructs.dev/packages/@pahud/cdk-github-oidc) construct.
+
+    More information about:  
+
+    - [Github OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/
+    - ["Configure AWS Credentials" Action For GitHub Actions](https://github.com/aws-actions/configure-aws-credentials/)
+2. Add your new role into your [Github fork secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) with name  `AWS_ROLE_ARN_TO_ASSUME`.
+3. In your forked repository, go to the "Actions" tabs, select the `run-e2e-tests` workflow.
+4. In the run-e2e-tests workflow page, select "Run workflow" and run it on the desired branch.
+
+> :warning: **Don't automatically run end-to-end tests on branch push or PRs**. A malicious attacker can submit a pull request to attack your AWS account. Ideally, use a blank account without any important workload/data, and limit `AWS_ROLE_ARN_TO_ASSUME` permission to least minimum privilege.
 ### Conventions
 
 Category | Convention
@@ -89,4 +179,4 @@ TODO
 
 See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
 
-We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
+We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
diff --git a/package.json b/package.json
@@ -14,6 +14,7 @@
     "package": "npm run package",
     "lerna-ci": "lerna exec -- npm ci",
     "lerna-test": "lerna exec -- npm run test",
+    "lerna-test:e2e": "lerna exec -- npm run test:e2e",
     "lerna-package": "lerna exec -- npm run package",
     "lerna-build": "lerna exec -- tsc",
     "lerna-lint": "lerna exec -- eslint \"./{src,tests}/**/*.ts ./src/*.ts\"",

diff --git a/packages/commons/package.json b/packages/commons/package.json
@@ -11,7 +11,9 @@
   },
   "scripts": {
     "commit": "commit",
-    "test": "jest  --detectOpenHandles --coverage --verbose",
+    "test": "npm run test:unit",
+    "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose",
+    "test:e2e": "echo 'Not Applicable'",
     "watch": "jest --watch",
     "build": "tsc",
     "lint": "eslint --ext .ts --fix --no-error-on-unmatched-pattern src tests",

diff --git a/packages/logger/jest.config.js b/packages/logger/jest.config.js
@@ -3,6 +3,7 @@ module.exports = {
     name: 'AWS Lambda Powertools utility: LOGGER',
     color: 'cyan',
   },
+  'runner': 'groups',
   'preset': 'ts-jest',
   'transform': {
     '^.+\\.ts?$': 'ts-jest',

diff --git a/packages/logger/package-lock.json b/packages/logger/package-lock.json
diff --git a/packages/logger/package.json b/packages/logger/package.json
@@ -11,7 +11,9 @@
   },
   "scripts": {
     "commit": "commit",
-    "test": "jest  --detectOpenHandles --coverage --verbose",
+    "test": "npm run test:unit",
+    "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose",
+    "test:e2e": "jest --group=e2e",
     "watch": "jest --watch",
     "build": "tsc",
     "lint": "eslint --ext .ts --fix --no-error-on-unmatched-pattern src tests",
@@ -53,6 +55,7 @@
     "eslint-import-resolver-typescript": "^2.5.0",
     "eslint-plugin-import": "^2.25.3",
     "jest": "^27.0.4",
+    "jest-runner-groups": "^2.1.0",
     "ts-jest": "^27.0.3",
     "ts-node": "^10.0.0",
     "typescript": "^4.1.3"

diff --git a/packages/logger/tests/unit/Logger.test.ts b/packages/logger/tests/unit/Logger.test.ts
@@ -1,3 +1,9 @@
+/**
+ * Test Logger class
+ *
+ * @group unit/logger/all
+ */
+
 import { context as dummyContext } from '../../../../tests/resources/contexts/hello-world';
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore

diff --git a/packages/logger/tests/unit/config/EnvironmentVariablesService.test.ts b/packages/logger/tests/unit/config/EnvironmentVariablesService.test.ts
@@ -1,3 +1,9 @@
+/**
+ * Test Logger EnvironmentVariablesService class
+ *
+ * @group unit/logger/all
+ */
+
 import { EnvironmentVariablesService } from '../../../src/config';
 
 describe('Class: EnvironmentVariablesService', () => {

diff --git a/packages/logger/tests/unit/formatter/PowertoolLogFormatter.test.ts b/packages/logger/tests/unit/formatter/PowertoolLogFormatter.test.ts
@@ -1,3 +1,9 @@
+/**
+ * Test Logger formatter
+ *
+ * @group unit/logger/all
+ */
+
 import { AssertionError, strictEqual } from 'assert';
 import { PowertoolLogFormatter } from '../../../src/formatter';
 import { UnformattedAttributes } from '../../../src/types';

diff --git a/packages/logger/tests/unit/helpers.test.ts b/packages/logger/tests/unit/helpers.test.ts
@@ -1,3 +1,9 @@
+/**
+ * Test Logger helpers
+ *
+ * @group unit/logger/all
+ */
+
 import { ConfigServiceInterface, EnvironmentVariablesService } from '../../src/config';
 import { LogFormatter, PowertoolLogFormatter } from '../../src/formatter';
 import { LoggerOptions } from '../../src/types';

diff --git a/packages/logger/tests/unit/middleware/middy.test.ts b/packages/logger/tests/unit/middleware/middy.test.ts
@@ -1,3 +1,9 @@
+/**
+ * Test Logger middleware
+ *
+ * @group unit/logger/all
+ */
+
 import { EnvironmentVariablesService } from '../../../src/config';
 import { injectLambdaContext } from '../../../src/middleware/middy';
 import { Logger } from './../../../src';

diff --git a/packages/metrics/package.json b/packages/metrics/package.json
@@ -11,7 +11,8 @@
   },
   "scripts": {
     "commit": "commit",
-    "test": "jest --group=unit --detectOpenHandles --coverage --verbose",
+    "test": "npm run test:unit",
+    "test:unit": "jest --group=unit --detectOpenHandles --coverage --verbose",
     "test:e2e": "jest --group=e2e",
     "watch": "jest --group=unit --watch ",
     "build": "tsc",

diff --git a/packages/metrics/tests/e2e/decorator.test.MyFunction.ts b/packages/metrics/tests/e2e/decorator.test.MyFunction.ts
@@ -14,7 +14,7 @@ const singleMetricName = process.env.EXPECTED_SINGLE_METRIC_NAME ?? 'MySingleMet
 const singleMetricUnit = (process.env.EXPECTED_SINGLE_METRIC_UNIT as MetricUnits) ?? MetricUnits.Percent;
 const singleMetricValue = process.env.EXPECTED_SINGLE_METRIC_VALUE ?? '2';
 
-const metrics = new Metrics({ namespace: namespace, service: serviceName });
+const metrics = new Metrics({ namespace: namespace, serviceName: serviceName });
 
 class Lambda implements LambdaInterface {