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
Firstly, [fork the repository](https://github.com/awslabs/aws-lambda-powertools-python/fork).
29
47
30
-
To setup your development environment, we recommend using our pre-configured Cloud environment: https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
48
+
To setup your development environment, we recommend using our pre-configured Cloud environment: <https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python>. Replace YOUR_USERNAME with your GitHub username or organization so the Cloud environment can target your fork accordingly.
31
49
32
50
Alternatively, you can use `make dev` within your local virtual environment.
33
51
@@ -47,22 +65,38 @@ GitHub provides additional document on [forking a repository](https://help.githu
47
65
48
66
You might find useful to run both the documentation website and the API reference locally while contributing:
49
67
50
-
***API reference**: `make docs-api-local`
51
-
***Docs website**: `make docs-local`
52
-
- If you prefer using Docker: `make docs-local-docker`
68
+
-**API reference**: `make docs-api-local`
69
+
-**Docs website**: `make docs-local`
70
+
- If you prefer using Docker: `make docs-local-docker`
|**Docstring**| We use a slight variation of Numpy convention with markdown to help generate more readable API references. |
79
+
|**Style guide**| We use black as well as flake8 extensions to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy). |
80
+
|**Core utilities**| Core utilities use a Class, always accept `service` as a constructor parameter, can work in isolation, and are also available in other languages implementation. |
81
+
|**Utilities**| Utilities are not as strict as core and focus on solving a developer experience problem while following the project [Tenets](https://awslabs.github.io/aws-lambda-powertools-python/#tenets). |
82
+
|**Exceptions**| Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`. |
83
+
|**Git commits**| We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly. |
84
+
|**API documentation**| API reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise. |
85
+
|**Documentation**| We treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features. |
**Docstring** | We use a slight variation of Numpy convention with markdown to help generate more readable API references.
59
-
**Style guide** | We use black as well as flake8 extensions to enforce beyond good practices [PEP8](https://pep8.org/). We use type annotations and enforce static type checking at CI (mypy).
60
-
**Core utilities** | Core utilities use a Class, always accept `service` as a constructor parameter, can work in isolation, and are also available in other languages implementation.
61
-
**Utilities** | Utilities are not as strict as core and focus on solving a developer experience problem while following the project [Tenets](https://awslabs.github.io/aws-lambda-powertools-python/#tenets).
62
-
**Exceptions** | Specific exceptions live within utilities themselves and use `Error` suffix e.g. `MetricUnitError`.
63
-
**Git commits** | We follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). We do not enforce conventional commits on contributors to lower the entry bar. Instead, we enforce a conventional PR title so our label automation and changelog are generated correctly.
64
-
**API documentation** | API reference docs are generated from docstrings which should have Examples section to allow developers to have what they need within their own IDE. Documentation website covers the wider usage, tips, and strive to be concise.
65
-
**Documentation** | We treat it like a product. We sub-divide content aimed at getting started (80% of customers) vs advanced usage (20%). We also ensure customers know how to unit test their code when using our features.
| Unit tests | Verify the smallest possible unit works. | Networking access is prohibited. Prefer Functional tests given our complexity. | Lightning fast (nsec to ms) |
94
+
| Functional tests | Guarantee functionality works as expected. It's a subset of integration test covering multiple units. | No external dependency. Prefer Fake implementations (in-memory) over Mocks and Stubs. | Fast (ms to few seconds at worst) |
95
+
| Integration tests | Gain confidence that code works with one or more external dependencies. | No need for a Lambda function. Use our code base against an external dependency _e.g., fetch an existing SSM parameter_. | Moderate to slow (a few minutes) |
96
+
| End-to-end tests | Gain confidence that a Lambda function with our code operates as expected. | It simulates how customers configure, deploy, and run their Lambda function - Event Source configuration, IAM permissions, etc. | Slow (minutes) |
97
+
| Performance tests | Ensure critical operations won't increase latency and costs to customers. | CI arbitrary hardware can make it flaky. We'll resume writing perf test after our new Integ/End have significant coverage. | Fast to moderate (a few seconds to a few minutes) |
98
+
99
+
**NOTE**: Functional tests are mandatory. We have plans to create a guide on how to create these different tests. Maintainers will help indicate whether additional tests are necessary and provide assistance as required.
66
100
67
101
## Finding contributions to work on
68
102
@@ -75,6 +109,7 @@ For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of
75
109
opensource-codeofconduct@amazon.com with any additional questions or comments.
76
110
77
111
## Security issue notifications
112
+
78
113
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
79
114
80
115
## Troubleshooting
@@ -85,9 +120,9 @@ When you are working on the codebase and you use the local API reference documen
85
120
86
121
This happens when:
87
122
88
-
* You did not install the local dev environment yet
123
+
- You did not install the local dev environment yet
89
124
- You can install dev deps with `make dev` command
90
-
* The code in the repository is raising an exception while the `pdoc` is scanning the codebase
125
+
- The code in the repository is raising an exception while the `pdoc` is scanning the codebase
91
126
- Unfortunately, this exception is not shown to you, but if you run, `poetry run pdoc --pdf aws_lambda_powertools`, the exception is shown and you can prevent the exception from being raised
92
127
- Once resolved the documentation should load correctly again
-[Releasing a documentation hotfix](#releasing-a-documentation-hotfix)
19
21
-[Maintain Overall Health of the Repo](#maintain-overall-health-of-the-repo)
20
22
-[Manage Roadmap](#manage-roadmap)
@@ -212,11 +214,85 @@ This will kick off the [Publishing workflow](https://github.com/awslabs/aws-lamb
212
214
213
215
### Run end to end tests
214
216
215
-
In order to run end to end tests you need to install CDK CLI first and bootstrap your account with `cdk bootstrap` command. For additional details follow [documentation](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html).
216
-
217
-
To run locally, export `AWS_PROFILE` environment variable and run `make e2e tests`. To run from GitHub Actions, use [run-e2e-tests workflow](https://github.com/awslabs/aws-lambda-powertools-python/actions/workflows/run-e2e-tests.yml) and pick the branch you want to run tests against.
218
-
219
-
**NOTE**: E2E tests are run as part of each merge to `develop` branch.
217
+
E2E tests are run on every push to `develop` or manually via [run-e2e-tests workflow](https://github.com/awslabs/aws-lambda-powertools-python/actions/workflows/run-e2e-tests.yml).
218
+
219
+
To run locally, you need [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_prerequisites) and an [account bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) (`cdk bootstrap`). With a default AWS CLI profile configured, or `AWS_PROFILE` environment variable set, run `make e2e tests`.
220
+
221
+
#### Structure
222
+
223
+
Our E2E framework relies on pytest fixtures to coordinate infrastructure and test parallelization (see [Workflow](#workflow)). You'll notice multiple `conftest.py`, `infrastructure.py`, and `handlers`.
224
+
225
+
-**`infrastructure`**. Uses CDK to define what a Stack for a given feature should look like. It inherits from `BaseInfrastructure` to handle all boilerplate and deployment logic necessary.
226
+
-**`conftest.py`**. Imports and deploys a given feature Infrastructure. Hierarchy matters. Top-level `conftest` deploys stacks only once and blocks I/O across all CPUs. Feature-level `conftest` deploys stacks in parallel, and once complete run all tests in parallel.
227
+
-**`handlers`**. Lambda function handlers that will be automatically deployed and exported as PascalCase for later use.
228
+
229
+
```shell
230
+
.
231
+
├── __init__.py
232
+
├── conftest.py # deploys Lambda Layer stack
233
+
├── logger
234
+
│ ├── __init__.py
235
+
│ ├── conftest.py # deploys LoggerStack
236
+
│ ├── handlers
237
+
│ │ └── basic_handler.py
238
+
│ ├── infrastructure.py # LoggerStack definition
239
+
│ └── test_logger.py
240
+
├── metrics
241
+
│ ├── __init__.py
242
+
│ ├── conftest.py # deploys MetricsStack
243
+
│ ├── handlers
244
+
│ │ ├── basic_handler.py
245
+
│ │ └── cold_start.py
246
+
│ ├── infrastructure.py # MetricsStack definition
247
+
│ └── test_metrics.py
248
+
├── tracer
249
+
│ ├── __init__.py
250
+
│ ├── conftest.py # deploys TracerStack
251
+
│ ├── handlers
252
+
│ │ ├── async_capture.py
253
+
│ │ └── basic_handler.py
254
+
│ ├── infrastructure.py # TracerStack definition
255
+
│ └── test_tracer.py
256
+
└── utils
257
+
├── Dockerfile
258
+
├── __init__.py
259
+
├── data_builder # build_service_name(), build_add_dimensions_input, etc.
260
+
├── data_fetcher # get_traces(), get_logs(), get_lambda_response(), etc.
261
+
├── infrastructure.py # base infrastructure like deploy logic, Layer Stack, etc.
262
+
```
263
+
264
+
#### Workflow
265
+
266
+
We parallelize our end-to-end tests to benefit from speed and isolate Lambda functions to ease assessing side effects (e.g., traces, logs, etc.). The following diagram demonstrates the process we take every time you use `make e2e`:
267
+
268
+
```mermaid
269
+
graph TD
270
+
A[make e2e test] -->Spawn{"Split and group tests <br>by feature and CPU"}
0 commit comments