chore: run e2e tests on demand

.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

.github/workflows/run-e2e-tests.yml

@@ -0,0 +1,30 @@
+name: run-e2e-tests
+on:
+  workflow_dispatch: {}
+jobs:
+  publish:
+    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/configure-aws-credentials@master
+      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

CONTRIBUTING.md

@@ -57,6 +57,81 @@ 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 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 Lambdas functions into your AWS Account. We use CDK lib for Typescript for creating infrastructure, and `aws sdk` 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 testing**
+
+**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**
+
+ `npm run test`
+
+You can run selective tests by restricting the group to the one you want. For instance `npx jest --group=unit/metrics/all`.
+
+**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>
+ */
+```
+
+and leverage `aws-cdk` package to programatically deploy and destroy stacks. See `metrics/tests/e2e/decorator.test.ts` as an example.
+
+
+**Run**
+
+To run unit tests you can either use projen task
+* `npm run test:e2e` which will only run jest integ tests
+* or jest directly `npx jest --group=e2e`
+
+You can run selective tests by restricting the group to the one you want. For instance `npx jest --group=e2e/other/example`.
+
+Two important env variable can be used:
+* `AWS_PROFILE` to use the right 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=ara npx jest --group=integ/other/example`
+
+**Automate**
+
+You can run the end-to-end tests automatically on your forked project by following these step.
+1. Create AWS Role
+  As mention earlier we are leveraging CDK to deploy and clean resources on AWS. Therefore to run those tests through github actions you will need to grant specific permissions to your workflow. To do so you can leverage [@pahud/cdk-github-oidc](https://constructs.dev/packages/@pahud/cdk-github-oidc) construct which setup the right resources to leverage [Github OpenID Connect](https://github.blog/changelog/2021-10-27-github-actions-secure-cloud-deployments-with-openid-connect/) mechanism.
+1. Add your new role into your Github fork secrets under `AWS_ROLE_ARN_TO_ASSUME`.
+1. Run manually `run-e2e-tests` workflow.
+
+> :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

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\"",

packages/commons/package.json

@@ -12,6 +12,7 @@
   "scripts": {
     "commit": "commit",
     "test": "jest  --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",

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',

packages/logger/package.json

@@ -11,7 +11,8 @@
   },
   "scripts": {
     "commit": "commit",
-    "test": "jest  --detectOpenHandles --coverage --verbose",
+    "test": "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 +54,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"

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

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', () => {

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';

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';

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';

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 {