You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+90
Original file line number
Diff line number
Diff line change
@@ -59,6 +59,96 @@ You can build and start a local docs website by running these two commands.
59
59
*`npm run docs-buildDockerImage` OR `docker build -t squidfunk/mkdocs-material ./docs/`
60
60
*`npm run docs-runLocalDocker` OR `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`
61
61
62
+
### Tests
63
+
64
+
Tests are under `tests` folder of each modules and split into two categories: unit tests and e2e (end-to-end) tests.
65
+
66
+
You can run each group separately or all together thanks to [jest-runner-groups](https://www.npmjs.com/package/jest-runner-groups).
67
+
68
+
Unit tests, under `tests/unit` folder are standard [Jest](https://jestjs.io) tests.
69
+
70
+
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.
71
+
72
+
73
+
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/).
74
+
75
+
When contributing to this repository, these end-to-end tests are run by the maintainers before merging a PR.
76
+
77
+
78
+
**Unit tests**
79
+
80
+
**Write**
81
+
82
+
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:
83
+
84
+
```typescript
85
+
/**
86
+
* Tests metrics
87
+
*
88
+
* @group unit/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
89
+
*/
90
+
```
91
+
92
+
**Run**
93
+
94
+
To run unit tests you can either use
95
+
* npm task `lerna-test:unit` (`npm run lerna-test:unit`) in root folder to run them all
96
+
* npm task `test:e2e` (`npm run test:unit`) in module folder (for example: `packages/metrics`) to run the module specific one
97
+
* 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`)
98
+
99
+
**e2e tests**
100
+
101
+
**Write**
102
+
103
+
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:
104
+
105
+
```typescript
106
+
/**
107
+
* Tests data lake catalog
108
+
*
109
+
* @group e2e/<YOUR CATEGORY>/<YOUR SUB CATEGORY>
110
+
*/
111
+
```
112
+
113
+
See `metrics/tests/e2e/decorator.test.ts` as an example.
114
+
115
+
116
+
**Run**
117
+
118
+
To run e2e tests you can either use
119
+
* npm task `lerna-test:e2e` (`npm run lerna-test:e2e`) in root folder
120
+
* npm task `test:e2e` (`npm run test:e2e`) in module folder (for example: `packages/metrics`) to run the module specific one
121
+
* 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`)
122
+
123
+
Two important env variable can be used:
124
+
*`AWS_PROFILE` to use the right AWS credentials
125
+
*`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).
126
+
127
+
Example: `DISABLE_TEARDOWN=true AWS_PROFILE=dev-account npx jest --group=e2e/metrics/decorator`
128
+
129
+
**Automate**
130
+
131
+
You can run the end-to-end tests automatically on your forked project by following these steps:
132
+
1. Create an IAM role in your target AWS account, with the least amount of privilege.
133
+
134
+
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.
135
+
136
+
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:
137
+
* Do not store credentials in your repository's code.
138
+
*[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.
139
+
*[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.
140
+
141
+
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.
-["Configure AWS Credentials" Action For GitHub Actions](https://github.com/aws-actions/configure-aws-credentials/)
147
+
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`.
148
+
3. In your forked repository, go to the "Actions" tabs, select the `run-e2e-tests` workflow.
149
+
4. In the run-e2e-tests workflow page, select "Run workflow" and run it on the desired branch.
150
+
151
+
> :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.
0 commit comments