Merge branch 'main' into havocDocs

Author: kalverra

.github/workflows/framework-golden-tests.yml

@@ -22,20 +22,16 @@ jobs:
             config: smoke.toml
             count: 1
             timeout: 10m
-          - name: TestLoad
-            config: load.toml
+          - name: TestPerformanceBaseline
+            config: performance_baseline.toml
             count: 1
             timeout: 10m
           - name: TestChaos
             config: chaos.toml
             count: 1
             timeout: 10m
-          - name: TestUpgradeAll
-            config: upgrade_all.toml
-            count: 1
-            timeout: 10m
-          - name: TestUpgradeSome
-            config: upgrade_some.toml
+          - name: TestUpgrade
+            config: upgrade.toml
             count: 1
             timeout: 10m
     steps:

.github/workflows/modgraph.yaml

@@ -0,0 +1,15 @@
+name: Module graph
+on:
+  pull_request:
+jobs:
+  modgraph:
+    runs-on: ubuntu-latest
+    name: modgraph
+    steps:
+      - name: Checkout the Repo
+        uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+      - name: Setup Go
+        uses: actions/setup-go@v5
+      - run: make modgraph
+      - name: Ensure clean modgraph
+        run: git diff --minimal --exit-code

CONTRIBUTING.md

@@ -0,0 +1,5 @@
+.PHONY: modgraph
+modgraph:
+	go install github.com/jmank88/[email protected]
+	go install github.com/jmank88/[email protected]
+	./modgraph > go.md

Makefile

@@ -15,10 +15,10 @@
     - [Configuration](./framework/configuration.md)
     - [Test Configuration](./framework/test_configuration_overrides.md)
     - [Components Persistence](framework/components/state.md)
+    - [Components Cleanup](framework/components/cleanup.md)
     - [Components Caching](framework/components/caching.md)
     - [External Environment](framework/components/external.md)
     - [Secrets]()
-    - [Docker](framework/docker.md)
     - [Observability Stack](framework/observability/observability_stack.md)
       - [Metrics](framework/observability/metrics.md)
       - [Logs](framework/observability/logs.md)
@@ -39,7 +39,7 @@
       - [Chainlink]()
       - [RPC]()
       - [Loki]()
-- [Testing](framework/testing.md)
+- [Testing Maturity Model](framework/testing.md)
   - [Smoke]()
   - [Performance]()
   - [Chaos]()

book/src/SUMMARY.md

@@ -0,0 +1,23 @@
+# Components Cleanup
+
+Managing state is challenging, especially in end-to-end testing, we use [ryuk](https://golang.testcontainers.org/features/garbage_collector/#ryuk) and following simple rules:
+- If `TESTCONTAINERS_RYUK_DISABLED=true`, no cleanup occurs — containers, volumes, and networks remain on your machine.
+
+  Feel free to use `ctf d rm` to remove containers when you are ready.
+- If `TESTCONTAINERS_RYUK_DISABLED` is unset, the test environment will be automatically cleaned up a few seconds after the test completes.
+
+
+Keep in mind that all components are mapped to [static ports](state.md), so without cleanup, only one environment can run at a time.
+
+This design choice simplifies debugging.
+
+A simplified command is available to prune unused volumes, containers, and build caches. Use it when you’re running low on space on your machine.
+```
+ctf d c
+```
+
+<div class="warning">
+
+The framework manages cleanup for both on-chain and off-chain Docker components. However, if your test involves actions like configuring Chainlink jobs, it's best practice to make these actions idempotent, so they can be applied reliably in any environment.
+
+</div>

book/src/framework/components/cleanup.md

@@ -46,7 +46,7 @@ Run the test
 CTF_CONFIGS=smoke.toml go test -v -run TestMe
 ```
 
-Remove containers
+Remove containers (read more about cleanup [here](components/cleanup.md))
 ```
 ctf d rm
 ```

book/src/framework/docker.md

@@ -37,7 +37,7 @@ Allow it to run in `System Settings -> Security Settings` (OS X)
 ![img.png](images/img.png)
 
 
-Create an `.envrc` file and do `source .envrc`
+Create an `.envrc` file and do `source .envrc` (we recommend to use [direnv](https://direnv.net/), so you don't need to load it every time)
 ```
 export TESTCONTAINERS_RYUK_DISABLED=true # do not remove containers while we develop locally
 ```

book/src/framework/first_test.md

@@ -1,24 +1,21 @@
-# "Golden" Templates
+# Testing Maturity Model
 
 [Here](https://github.com/smartcontractkit/chainlink-testing-framework/actions/runs/11739154666/job/32703095118?pr=1311) are our "golden" templates for end-to-end tests, covering every test type:
 
 - `Smoke`
-- `Performance`
+- `PerformanceBaseline`
 - `Chaos`
 - `Upgrade`
 
 These tests act as a maturity model and are implemented across all our products.
 
-Run them locally:
+Refer to this README to understand the rationale behind our testing approach and to explore the stages of maturity in end-to-end testing.
+
+## Developing
+Run the tests locally
 ```
 CTF_CONFIGS=smoke.toml go test -v -run TestSmoke
-CTF_CONFIGS=load.toml go test -v -run TestLoad
+CTF_CONFIGS=performance_baseline.toml go test -v -run TestPerformanceBaseline
 CTF_CONFIGS=chaos.toml go test -v -run TestChaos
-CTF_CONFIGS=upgrade_some.toml go test -v -run TestUpgradeSome
+CTF_CONFIGS=upgrade.toml go test -v -run TestUpgrade
 ```
-
-Use this [workflow](https://github.com/smartcontractkit/chainlink-testing-framework/actions/runs/11739154666/workflow?pr=1311) as a starting point for developing a new end-to-end integration test.
-
-Set the count to 5-10 during development, and once stable, set the timeout and proceed to merge.
-
-If you need to structure a lot of different tests (not only end-to-end) follow [this](https://github.com/smartcontractkit/.github/tree/main/.github/workflows) guide.