more docs

smartcontractkit · Oct 31, 2024 · e8fa0a6 · e8fa0a6
1 parent 5e31f91
commit e8fa0a6
Show file tree

Hide file tree

Showing 6 changed files with 152 additions and 140 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -34,10 +34,12 @@
       - [Chainlink]()
       - [RPC]()
       - [Loki]()
+- [Continuous Integration](ci/ci.md)
 - [Libraries](./libraries.md)
   - [Seth](./libs/seth.md)
   - [WASP](./libs/wasp.md)
   - [Havoc](./libs/havoc.md)
+  - [K8s Test Runner](k8s-test-runner/k8s-test-runner.md)
 
 ---
 

diff --git a/book/src/ci/ci.md b/book/src/ci/ci.md
@@ -0,0 +1,5 @@
+# Continuous Integration
+
+Here we describe our good practices for structuring different types of tests in Continuous Integration (GitHub Actions).
+
+Follow [this](https://github.com/smartcontractkit/.github/tree/main/.github/workflows) guide.
diff --git a/book/src/k8s-test-runner/k8s-test-runner.md b/book/src/k8s-test-runner/k8s-test-runner.md
@@ -0,0 +1,140 @@
+## Preparing to Run Tests on Staging
+
+Ensure you complete the following steps before executing tests on the staging environment:
+
+1. **Connect to the VPN**
+
+2. **AWS Login with Staging Profile**
+
+   Authenticate to AWS using your staging profile, specifically with the `StagingEKSAdmin` role. Execute the following command:
+
+   ```sh
+   aws sso login --profile staging
+   ```
+
+3. **Verify Authorization**
+
+   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.
+
+## Running Tests
+
+### Creating an Image with the Test Binary
+
+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:
+
+1. Compiles test binary under `<path-to-test-folder>`
+2. Creates a docker image with the test binary
+3. Pushes the docker image to the image registry (e.g. Staging ECR)
+
+```sh
+go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-tag "<image-tag>" "<path-to-test-folder>"
+```
+
+Where `image-tag` should be a descriptive name for your test, such as "mercury-load-tests".
+
+### Running the Test in Kubernetes
+
+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.
+
+```
+go run ./cmd/main.go run -c "<path-to-test-runner-toml-config>"
+```
+
+The TOML config should specify the test runner configuration as follows:
+
+```
+namespace = "e2e-tests"
+rbac_role_name = "" # RBAC role name for the chart
+image_registry_url = "" # URL to the ECR containing the test binary image, e.g., staging ECR URL
+image_name = "k8s-test-runner"
+image_tag = ""  # The image tag to use, like "mercury-load-tests" (see readme above)
+job_count = "1"
+test_name = "TestMercuryLoad/all_endpoints"
+test_timeout = "24h"
+test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
+test_config_file_path = "/Users/lukasz/Documents/test-configs/load-staging-testnet.toml"
+resources_requests_cpu = "1000m"
+resources_requests_memory = "512Mi"
+resources_limits_cpu = "2000m"
+resources_limits_memory = "1024Mi"
+[envs]
+WASP_LOG_LEVEL = "info"
+TEST_LOG_LEVEL = "info"
+MERCURY_TEST_LOG_LEVEL = "info"
+```
+
+Where:
+
+- `test_name` is the name of the test to run (must be included in the test binary).
+- `test_config_env_name` is the name of the environment variable used to provide the test configuration for the test (optional).
+- `test_config_file_path` is the path to the configuration file for the test (optional).
+
+## Using K8s Test Runner on CI
+
+### Example
+
+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.
+
+```
+- name: Download K8s Test Runner
+    run: |
+        mkdir -p k8s-test-runner
+        cd k8s-test-runner
+        curl -L -o k8s-test-runner.tar.gz https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/v0.2.4/test-runner.tar.gz
+        tar -xzf k8s-test-runner.tar.gz
+        chmod +x k8s-test-runner-linux-amd64
+```
+
+Alternatively, you can place the k8s-test-runner package within your repository and unpack it:
+
+```
+- name: Unpack K8s Test Runner
+    run: |
+        cd e2e_tests
+        mkdir -p k8s-test-runner
+        tar -xzf k8s-test-runner-v0.0.1.tar.gz -C k8s-test-runner
+        chmod +x k8s-test-runner/k8s-test-runner-linux-amd64
+```
+
+Then:
+
+```
+- name: Build K8s Test Runner Image
+    if: github.event.inputs.test-type == 'load' && github.event.inputs.rebuild-test-image == 'yes'
+    run: |
+        cd e2e_tests/k8s-test-runner
+
+        ./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"
+
+- name: Run Test in K8s
+    run: |
+        cd e2e_tests/k8s-test-runner
+
+        cat << EOF > config.toml
+        namespace = "e2e-tests"
+        rbac_role_name = "" # RBAC role name for the chart
+        image_registry_url = "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com"
+        image_name = "k8s-test-runner"
+        image_tag = "mercury-load-test"
+        job_count = "1"
+        chart_path = "./chart"
+        test_name = "TestMercuryLoad/all_endpoints"
+        test_timeout = "24h"
+        resources_requests_cpu = "1000m"
+        resources_requests_memory = "512Mi"
+        resources_limits_cpu = "2000m"
+        resources_limits_memory = "1024Mi"
+        test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
+        test_config_base64 = "${{ steps.conditional-env-vars.outputs.LOAD_TEST_BASE64_TOML_CONTENT }}"
+        [envs]
+        WASP_LOG_LEVEL = "info"
+        TEST_LOG_LEVEL = "info"
+        MERCURY_TEST_LOG_LEVEL = "info"
+        EOF
+
+        ./k8s-test-runner-linux-amd64 run -c config.toml
+```
+
+## Release
+
+Run `./package <version>`
diff --git a/book/src/lib/blockchain.md b/book/src/lib/blockchain.md
@@ -33,6 +33,6 @@ type MetisClient struct {
 }
 ```
 
-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).
+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).
 
 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`.
diff --git a/k8s-test-runner/README.md b/k8s-test-runner/README.md
@@ -1,140 +1,5 @@
-## Preparing to Run Tests on Staging
+# K8s Test Runner
 
-Ensure you complete the following steps before executing tests on the staging environment:
+A tool to build and run arbitrary Go code in `k8s` the easy way.
 
-1. **Connect to the VPN**
-
-2. **AWS Login with Staging Profile**
-
-   Authenticate to AWS using your staging profile, specifically with the `StagingEKSAdmin` role. Execute the following command:
-
-   ```sh
-   aws sso login --profile staging
-   ```
-
-3. **Verify Authorization**
-
-   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.
-
-## Running Tests
-
-### Creating an Image with the Test Binary
-
-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:
-
-1. Compiles test binary under `<path-to-test-folder>`
-2. Creates a docker image with the test binary
-3. Pushes the docker image to the image registry (e.g. Staging ECR)
-
-```sh
-go run ./cmd/main.go create-test-image --image-registry-url <staging-ecr-registry-url> --image-tag "<image-tag>" "<path-to-test-folder>"
-```
-
-Where `image-tag` should be a descriptive name for your test, such as "mercury-load-tests".
-
-### Running the Test in Kubernetes
-
-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.
-
-```
-go run ./cmd/main.go run -c "<path-to-test-runner-toml-config>"
-```
-
-The TOML config should specify the test runner configuration as follows:
-
-```
-namespace = "e2e-tests"
-rbac_role_name = "" # RBAC role name for the chart
-image_registry_url = "" # URL to the ECR containing the test binary image, e.g., staging ECR URL
-image_name = "k8s-test-runner"
-image_tag = ""  # The image tag to use, like "mercury-load-tests" (see readme above)
-job_count = "1"
-test_name = "TestMercuryLoad/all_endpoints"
-test_timeout = "24h"
-test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
-test_config_file_path = "/Users/lukasz/Documents/test-configs/load-staging-testnet.toml"
-resources_requests_cpu = "1000m"
-resources_requests_memory = "512Mi"
-resources_limits_cpu = "2000m"
-resources_limits_memory = "1024Mi"
-[envs]
-WASP_LOG_LEVEL = "info"
-TEST_LOG_LEVEL = "info"
-MERCURY_TEST_LOG_LEVEL = "info"
-```
-
-Where:
-
-- `test_name` is the name of the test to run (must be included in the test binary).
-- `test_config_env_name` is the name of the environment variable used to provide the test configuration for the test (optional).
-- `test_config_file_path` is the path to the configuration file for the test (optional).
-
-## Using K8s Test Runner on CI
-
-### Example
-
-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.
-
-```
-- name: Download K8s Test Runner
-    run: |
-        mkdir -p k8s-test-runner
-        cd k8s-test-runner
-        curl -L -o k8s-test-runner.tar.gz https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/v0.2.4/test-runner.tar.gz
-        tar -xzf k8s-test-runner.tar.gz
-        chmod +x k8s-test-runner-linux-amd64
-```
-
-Alternatively, you can place the k8s-test-runner package within your repository and unpack it:
-
-```
-- name: Unpack K8s Test Runner
-    run: |
-        cd e2e_tests
-        mkdir -p k8s-test-runner
-        tar -xzf k8s-test-runner-v0.0.1.tar.gz -C k8s-test-runner
-        chmod +x k8s-test-runner/k8s-test-runner-linux-amd64
-```
-
-Then:
-
-```
-- name: Build K8s Test Runner Image
-    if: github.event.inputs.test-type == 'load' && github.event.inputs.rebuild-test-image == 'yes'
-    run: |
-        cd e2e_tests/k8s-test-runner
-
-        ./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"
-
-- name: Run Test in K8s
-    run: |
-        cd e2e_tests/k8s-test-runner
-
-        cat << EOF > config.toml
-        namespace = "e2e-tests"
-        rbac_role_name = "" # RBAC role name for the chart
-        image_registry_url = "${{ secrets.AWS_ACCOUNT_ID_STAGING }}.dkr.ecr.${{ secrets.AWS_REGION }}.amazonaws.com"
-        image_name = "k8s-test-runner"
-        image_tag = "mercury-load-test"
-        job_count = "1"
-        chart_path = "./chart"
-        test_name = "TestMercuryLoad/all_endpoints"
-        test_timeout = "24h"
-        resources_requests_cpu = "1000m"
-        resources_requests_memory = "512Mi"
-        resources_limits_cpu = "2000m"
-        resources_limits_memory = "1024Mi"
-        test_config_base64_env_name = "LOAD_TEST_BASE64_TOML_CONTENT"
-        test_config_base64 = "${{ steps.conditional-env-vars.outputs.LOAD_TEST_BASE64_TOML_CONTENT }}"
-        [envs]
-        WASP_LOG_LEVEL = "info"
-        TEST_LOG_LEVEL = "info"
-        MERCURY_TEST_LOG_LEVEL = "info"
-        EOF
-
-        ./k8s-test-runner-linux-amd64 run -c config.toml
-```
-
-## Release
-
-Run `./package <version>`
+[![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)
diff --git a/lib/README.md b/lib/README.md
@@ -1,3 +1,3 @@
 # Framework v1 (Deprecated)
 
-[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/lib.html)
+[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/lib.html)