Skip to content

Commit e8fa0a6

Browse files
skudasovskudasov
committed
more docs
1 parent 5e31f91 commit e8fa0a6

File tree

6 files changed

+152
-140
lines changed

6 files changed

+152
-140
lines changed

‎book/src/SUMMARY.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,12 @@
3434
- [Chainlink]()
3535
- [RPC]()
3636
- [Loki]()
37+
- [Continuous Integration](ci/ci.md)
3738
- [Libraries](./libraries.md)
3839
- [Seth](./libs/seth.md)
3940
- [WASP](./libs/wasp.md)
4041
- [Havoc](./libs/havoc.md)
42+
- [K8s Test Runner](k8s-test-runner/k8s-test-runner.md)
4143

4244
---
4345

‎book/src/ci/ci.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Continuous Integration
2+
3+
Here we describe our good practices for structuring different types of tests in Continuous Integration (GitHub Actions).
4+
5+
Follow [this](https://github.com/smartcontractkit/.github/tree/main/.github/workflows) guide.

‎book/src/k8s-test-runner/k8s-test-runner.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
## Preparing to Run Tests on Staging
2+
3+
Ensure you complete the following steps before executing tests on the staging environment:
4+
5+
1. **Connect to the VPN**
6+
7+
2. **AWS Login with Staging Profile**
8+
9+
Authenticate to AWS using your staging profile, specifically with the `StagingEKSAdmin` role. Execute the following command:
10+
11+
```sh
12+
aws sso login --profile staging
13+
```
14+
15+
3. **Verify Authorization**
16+
17+
Confirm your authorization status by listing the namespaces in the staging cluster. Run `kubectl get namespaces`. If you see a list of namespaces, this indicates successful access to the staging cluster.
18+
19+
## Running Tests
20+
21+
### Creating an Image with the Test Binary
22+
23+
Before running tests, you must create a Docker image containing the test binary. To do this, execute the `create-test-image` command and provide the path to the test folder you wish to package. This command:
24+
25+
1. Compiles test binary under `<path-to-test-folder>`
26+
2. Creates a docker image with the test binary
27+
3. Pushes the docker image to the image registry (e.g. Staging ECR)
28+
29+
```sh
30+
go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-tag "<image-tag>" "<path-to-test-folder>"
31+
```
32+
33+
Where `image-tag` should be a descriptive name for your test, such as "mercury-load-tests".
34+
35+
### Running the Test in Kubernetes
36+
37+
If a Docker image containing the test binary is available in an image registry (such as staging ECR), use `run` command to execute the test in K8s.
38+
39+
```
40+
go run ./cmd/main.go run -c "<path-to-test-runner-toml-config>"
41+
```
42+
43+
The TOML config should specify the test runner configuration as follows:
44+
45+
```
46+
namespace = "e2e-tests"
47+
rbac_role_name = "" # RBAC role name for the chart
48+
image_registry_url = "" # URL to the ECR containing the test binary image, e.g., staging ECR URL
49+
image_name = "k8s-test-runner"
50+
image_tag = "" # The image tag to use, like "mercury-load-tests" (see readme above)
51+
job_count = "1"
52+
test_name = "TestMercuryLoad/all_endpoints"
53+
test_timeout = "24h"
54+
test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
55+
test_config_file_path = "/Users/lukasz/Documents/test-configs/load-staging-testnet.toml"
56+
resources_requests_cpu = "1000m"
57+
resources_requests_memory = "512Mi"
58+
resources_limits_cpu = "2000m"
59+
resources_limits_memory = "1024Mi"
60+
[envs]
61+
WASP_LOG_LEVEL = "info"
62+
TEST_LOG_LEVEL = "info"
63+
MERCURY_TEST_LOG_LEVEL = "info"
64+
```
65+
66+
Where:
67+
68+
- `test_name` is the name of the test to run (must be included in the test binary).
69+
- `test_config_env_name` is the name of the environment variable used to provide the test configuration for the test (optional).
70+
- `test_config_file_path` is the path to the configuration file for the test (optional).
71+
72+
## Using K8s Test Runner on CI
73+
74+
### Example
75+
76+
This example demonstrates the process step by step. First, it shows how to download the Kubernetes Test Runner. Next, it details the use of the Test Runner to create a test binary specifically for the Mercury "e2e_tests/staging_prod/tests/load" test package. Finally, it describes executing the test in Kubernetes using a customized test runner configuration.
77+
78+
```
79+
- name: Download K8s Test Runner
80+
run: |
81+
mkdir -p k8s-test-runner
82+
cd k8s-test-runner
83+
curl -L -o k8s-test-runner.tar.gz https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/v0.2.4/test-runner.tar.gz
84+
tar -xzf k8s-test-runner.tar.gz
85+
chmod +x k8s-test-runner-linux-amd64
86+
```
87+
88+
Alternatively, you can place the k8s-test-runner package within your repository and unpack it:
89+
90+
```
91+
- name: Unpack K8s Test Runner
92+
run: |
93+
cd e2e_tests
94+
mkdir -p k8s-test-runner
95+
tar -xzf k8s-test-runner-v0.0.1.tar.gz -C k8s-test-runner
96+
chmod +x k8s-test-runner/k8s-test-runner-linux-amd64
97+
```
98+
99+
Then:
100+
101+
```
102+
- name: Build K8s Test Runner Image
103+
if: github.event.inputs.test-type == 'load' && github.event.inputs.rebuild-test-image == 'yes'
104+
run: |
105+
cd e2e_tests/k8s-test-runner
106+
107+
./k8s-test-runner-linux-amd64 create-test-image --image-registry-url "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com" --image-tag "mercury-load-test" "../staging_prod/tests/load"
108+
109+
- name: Run Test in K8s
110+
run: |
111+
cd e2e_tests/k8s-test-runner
112+
113+
cat << EOF > config.toml
114+
namespace = "e2e-tests"
115+
rbac_role_name = "" # RBAC role name for the chart
116+
image_registry_url = "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com"
117+
image_name = "k8s-test-runner"
118+
image_tag = "mercury-load-test"
119+
job_count = "1"
120+
chart_path = "./chart"
121+
test_name = "TestMercuryLoad/all_endpoints"
122+
test_timeout = "24h"
123+
resources_requests_cpu = "1000m"
124+
resources_requests_memory = "512Mi"
125+
resources_limits_cpu = "2000m"
126+
resources_limits_memory = "1024Mi"
127+
test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
128+
test_config_base64 = "${{ steps.conditional-env-vars.outputs.LOAD_TEST_BASE64_TOML_CONTENT }}"
129+
[envs]
130+
WASP_LOG_LEVEL = "info"
131+
TEST_LOG_LEVEL = "info"
132+
MERCURY_TEST_LOG_LEVEL = "info"
133+
EOF
134+
135+
./k8s-test-runner-linux-amd64 run -c config.toml
136+
```
137+
138+
## Release
139+
140+
Run `./package <version>`

‎book/src/lib/blockchain.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,6 @@ type MetisClient struct {
3333
}
3434
```
3535

36-
Now we need to let other libraries (like our tests in the main Chainlink repo) that this integration exists. So we add the new implementation to the [known_networks.go](./known_networks.go) file. We can then add that network to our tests' own [known_networks.go](https://github.com/smartcontractkit/chainlink/blob/develop/integration-tests/known_networks.go) file (it's annoying, there are plans to simplify).
36+
Now we need to let other libraries (like our tests in the main Chainlink repo) that this integration exists. So we add the new implementation to the [known_networks.go](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/lib/blockchain/known_networks.go) file. We can then add that network to our tests' own [known_networks.go](https://github.com/smartcontractkit/chainlink/blob/develop/integration-tests/known_networks.go) file (it's annoying, there are plans to simplify).
3737

3838
Now our Metis integration is the exact same as our base Ethereum one, which doesn't do us too much good. I'm assuming you came here to make some changes, so first let's find out what we need to change. This is a mix of reading developer documentation on the chain you're testing and trial and error. Mostly the latter in later stages. In the case of Metis, like many L2s, they [have their own spin on gas fees](https://docs.metis.io/dev/protocol-in-detail/transaction-fees-on-the-metis-platform). They also only support Legacy transactions. So we'll need to override any methods that deal with gas estimations, `Fund`, `DeployContract`, and `ReturnFunds`.

‎k8s-test-runner/README.md‎

Lines changed: 3 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,5 @@
1-
## Preparing to Run Tests on Staging
1+
# K8s Test Runner
22

3-
Ensure you complete the following steps before executing tests on the staging environment:
3+
A tool to build and run arbitrary Go code in `k8s` the easy way.
44

5-
1. **Connect to the VPN**
6-
7-
2. **AWS Login with Staging Profile**
8-
9-
Authenticate to AWS using your staging profile, specifically with the `StagingEKSAdmin` role. Execute the following command:
10-
11-
```sh
12-
aws sso login --profile staging
13-
```
14-
15-
3. **Verify Authorization**
16-
17-
Confirm your authorization status by listing the namespaces in the staging cluster. Run `kubectl get namespaces`. If you see a list of namespaces, this indicates successful access to the staging cluster.
18-
19-
## Running Tests
20-
21-
### Creating an Image with the Test Binary
22-
23-
Before running tests, you must create a Docker image containing the test binary. To do this, execute the `create-test-image` command and provide the path to the test folder you wish to package. This command:
24-
25-
1. Compiles test binary under `<path-to-test-folder>`
26-
2. Creates a docker image with the test binary
27-
3. Pushes the docker image to the image registry (e.g. Staging ECR)
28-
29-
```sh
30-
go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-tag "<image-tag>" "<path-to-test-folder>"
31-
```
32-
33-
Where `image-tag` should be a descriptive name for your test, such as "mercury-load-tests".
34-
35-
### Running the Test in Kubernetes
36-
37-
If a Docker image containing the test binary is available in an image registry (such as staging ECR), use `run` command to execute the test in K8s.
38-
39-
```
40-
go run ./cmd/main.go run -c "<path-to-test-runner-toml-config>"
41-
```
42-
43-
The TOML config should specify the test runner configuration as follows:
44-
45-
```
46-
namespace = "e2e-tests"
47-
rbac_role_name = "" # RBAC role name for the chart
48-
image_registry_url = "" # URL to the ECR containing the test binary image, e.g., staging ECR URL
49-
image_name = "k8s-test-runner"
50-
image_tag = "" # The image tag to use, like "mercury-load-tests" (see readme above)
51-
job_count = "1"
52-
test_name = "TestMercuryLoad/all_endpoints"
53-
test_timeout = "24h"
54-
test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
55-
test_config_file_path = "/Users/lukasz/Documents/test-configs/load-staging-testnet.toml"
56-
resources_requests_cpu = "1000m"
57-
resources_requests_memory = "512Mi"
58-
resources_limits_cpu = "2000m"
59-
resources_limits_memory = "1024Mi"
60-
[envs]
61-
WASP_LOG_LEVEL = "info"
62-
TEST_LOG_LEVEL = "info"
63-
MERCURY_TEST_LOG_LEVEL = "info"
64-
```
65-
66-
Where:
67-
68-
- `test_name` is the name of the test to run (must be included in the test binary).
69-
- `test_config_env_name` is the name of the environment variable used to provide the test configuration for the test (optional).
70-
- `test_config_file_path` is the path to the configuration file for the test (optional).
71-
72-
## Using K8s Test Runner on CI
73-
74-
### Example
75-
76-
This example demonstrates the process step by step. First, it shows how to download the Kubernetes Test Runner. Next, it details the use of the Test Runner to create a test binary specifically for the Mercury "e2e_tests/staging_prod/tests/load" test package. Finally, it describes executing the test in Kubernetes using a customized test runner configuration.
77-
78-
```
79-
- name: Download K8s Test Runner
80-
run: |
81-
mkdir -p k8s-test-runner
82-
cd k8s-test-runner
83-
curl -L -o k8s-test-runner.tar.gz https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/v0.2.4/test-runner.tar.gz
84-
tar -xzf k8s-test-runner.tar.gz
85-
chmod +x k8s-test-runner-linux-amd64
86-
```
87-
88-
Alternatively, you can place the k8s-test-runner package within your repository and unpack it:
89-
90-
```
91-
- name: Unpack K8s Test Runner
92-
run: |
93-
cd e2e_tests
94-
mkdir -p k8s-test-runner
95-
tar -xzf k8s-test-runner-v0.0.1.tar.gz -C k8s-test-runner
96-
chmod +x k8s-test-runner/k8s-test-runner-linux-amd64
97-
```
98-
99-
Then:
100-
101-
```
102-
- name: Build K8s Test Runner Image
103-
if: github.event.inputs.test-type == 'load' && github.event.inputs.rebuild-test-image == 'yes'
104-
run: |
105-
cd e2e_tests/k8s-test-runner
106-
107-
./k8s-test-runner-linux-amd64 create-test-image --image-registry-url "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com" --image-tag "mercury-load-test" "../staging_prod/tests/load"
108-
109-
- name: Run Test in K8s
110-
run: |
111-
cd e2e_tests/k8s-test-runner
112-
113-
cat << EOF > config.toml
114-
namespace = "e2e-tests"
115-
rbac_role_name = "" # RBAC role name for the chart
116-
image_registry_url = "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com"
117-
image_name = "k8s-test-runner"
118-
image_tag = "mercury-load-test"
119-
job_count = "1"
120-
chart_path = "./chart"
121-
test_name = "TestMercuryLoad/all_endpoints"
122-
test_timeout = "24h"
123-
resources_requests_cpu = "1000m"
124-
resources_requests_memory = "512Mi"
125-
resources_limits_cpu = "2000m"
126-
resources_limits_memory = "1024Mi"
127-
test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
128-
test_config_base64 = "${{ steps.conditional-env-vars.outputs.LOAD_TEST_BASE64_TOML_CONTENT }}"
129-
[envs]
130-
WASP_LOG_LEVEL = "info"
131-
TEST_LOG_LEVEL = "info"
132-
MERCURY_TEST_LOG_LEVEL = "info"
133-
EOF
134-
135-
./k8s-test-runner-linux-amd64 run -c config.toml
136-
```
137-
138-
## Release
139-
140-
Run `./package <version>`
5+
[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/k8s-test-runner/k8s-test-runner.html)

‎lib/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Framework v1 (Deprecated)
22

3-
[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/lib.html)
3+
[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/lib.html)

0 commit comments

Comments
 (0)