v2 docs

smartcontractkit · Oct 30, 2024 · 4764f4e · 4764f4e
1 parent 112a680
commit 4764f4e
Show file tree

Hide file tree

Showing 16 changed files with 404 additions and 55 deletions.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -1,17 +1,29 @@
 # Summary
 
 - [Overview](./overview.md)
-- [Libraries](./libraries.md)
-  - [Seth](./libs/seth.md)
-  - [WASP](./libs/wasp.md)
-  - [Havoc](./libs/havoc.md)
 - [Framework](./framework/overview.md)
+    - [Overview](./framework/overview.md)
     - [Getting Started](./framework/getting_started.md)
+    - [First Test](./framework/first_test.md)
+    - [Connecting Chainlink Node](./framework/connecting_chainlink_node.md)
+    - [Connecting Chainlink Node (Multiple networks)]()
+    - [Basic NodeSet Environment](./framework/basic_environment.md)
     - [CLI](./framework/cli.md)
+    - [Configuration](./framework/configuration.md)
+    - [Observability Stack](framework/observability_stack.md)
+      - [Metrics]()
+      - [Logs](framework/logs.md)
+      - [Profiling](framework/profiling.md)
+      - [Traces]()
+      - [Debugger]()
     - [Components](framework/components/overview.md)
-      - [Blockchains](framework/components/blockchains/overview.md)
-        - [Anvil](framework/components/blockchains/anvil.md)
+        - [Blockchains](framework/components/blockchains/overview.md)
+            - [Anvil](framework/components/blockchains/anvil.md)
     - [Secrets](./secrets.md)
+- [Libraries](./libraries.md)
+  - [Seth](./libs/seth.md)
+  - [WASP](./libs/wasp.md)
+  - [Havoc](./libs/havoc.md)
 
 ---
 

diff --git a/book/src/framework/basic_environment.md b/book/src/framework/basic_environment.md
@@ -0,0 +1,75 @@
+# Chainlink Cluster (NodeSet) Environment Test
+
+Create a configuration file `smoke.toml`
+```toml
+funds_eth = 30.0
+
+[blockchain_a]
+  chain_id = "31337"
+  image = "f4hrenh9it/foundry:latest"
+  port = "8545"
+  type = "anvil"
+
+[contracts]
+
+[data_provider]
+  port = 9111
+
+[nodeset]
+  nodes = 5
+  override_mode = "all"
+
+  [[nodeset.node_specs]]
+
+    [nodeset.node_specs.db]
+      image = "postgres:15.6"
+      pull_image = true
+
+    [nodeset.node_specs.node]
+      image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
+      pull_image = true
+
+```
+
+Create a file `smoke_test.go`
+```golang
+package yourpackage_test
+
+import (
+	"fmt"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/fake"
+	ns "github.com/smartcontractkit/chainlink-testing-framework/framework/components/simple_node_set"
+	"github.com/smartcontractkit/chainlink/e2e/capabilities/components/onchain"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+type Config struct {
+	FundingETH         float64           `toml:"funds_eth"`
+	BlockchainA        *blockchain.Input `toml:"blockchain_a" validate:"required"`
+	Contracts          *onchain.Input    `toml:"contracts" validate:"required"`
+	MockerDataProvider *fake.Input       `toml:"data_provider" validate:"required"`
+	NodeSet            *ns.Input         `toml:"nodeset" validate:"required"`
+}
+
+func TestNodeSet(t *testing.T) {
+	in, err := framework.Load[Config](t)
+	require.NoError(t, err)
+
+	// deploy docker test environment
+	bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+	require.NoError(t, err)
+	dp, err := fake.NewFakeDataProvider(in.MockerDataProvider)
+	require.NoError(t, err)
+	out, err := ns.NewSharedDBNodeSet(in.NodeSet, bc, dp.BaseURLDocker)
+	require.NoError(t, err)
+}
+```
+
+Run it
+```bash
+go test -v -run TestNodeSet
+```
+
diff --git a/book/src/framework/cli.md b/book/src/framework/cli.md
@@ -1,11 +1,6 @@
 ## CLI
-### Install
-```
-go get github.com/smartcontractkit/chainlink-testing-framework/framework/cmd && \
-go install github.com/smartcontractkit/chainlink-testing-framework/framework/cmd && \
-mv ~/go/bin/cmd ~/go/bin/ctf
-```
-### Usage
+
+To keep documentation simple we provide CLI docs in "help" format
 ```
 ctf -h
 ```
diff --git a/book/src/framework/components/blockchains/anvil.md b/book/src/framework/components/blockchains/anvil.md
@@ -1,25 +1,33 @@
 # Anvil
 [Anvil](https://book.getfoundry.sh/anvil/) is a Foundry local EVM blockchain simulator
 
-Use `docker_cmd_params = ['--block-time=1', '...']` to provide more params
-
 ## Configuration
 ```toml
 [blockchain_a]
+  # Blockchain node type, can be "anvil" or "geth"
+  type = "anvil"
+  # Chain ID
   chain_id = "31337"
+  # Anvil command line params, ex.: docker_cmd_params = ['--block-time=1', '...']
   docker_cmd_params = []
+  # Docker image and tag
   image = "ghcr.io/gakonst/foundry:latest"
+  # External port to expose
   port = "8545"
+  # Pulls the image every time if set to 'true', used like that in CI. Can be set to 'false' to speed up local runs
   pull_image = false
-  type = "anvil"
 
+  # Outputs are the results of deploying a component that can be used by another component
   [blockchain_a.out]
     chain_id = "31337"
+    # If 'use_cache' equals 'true' we skip component setup when we run the test and return the outputs
     use_cache = true
 
     [[blockchain_a.out.nodes]]
+      # URLs to access the node(s) inside docker network, used by other components
       docker_internal_http_url = "http://anvil-14411:8545"
       docker_internal_ws_url = "ws://anvil-14411:8545"
+      # URLs to access the node(s) on your host machine or in CI
       http_url = "http://127.0.0.1:33955"
       ws_url = "ws://127.0.0.1:33955"
 ```

diff --git a/book/src/framework/configuration.md b/book/src/framework/configuration.md
@@ -0,0 +1,12 @@
+# Configuration
+
+### Environment variables
+|             Name             |                                                                      Description                                                                       |          Possible values | Default |        Required?         |
+|:----------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------:|-------------------------:|:-------:|:------------------------:|
+|         CTF_CONFIGS          | Path(s) to test config files. <br/>Can be more than one, ex.: smoke.toml,smoke_1.toml,smoke_2.toml.<br/>First filepath will hold all the merged values | Any valid TOML file path |         |            ✅             |
+|        CTF_LOG_LEVEL         |                                                                   Harness log level                                                                    | `info`, `debug`, `trace` | `info`  |            🚫            |
+|       CTF_LOKI_STREAM        |                                                Streams all components logs to `Loki`, see params below                                                 |          `true`, `false` | `false` |            🚫            |
+|           LOKI_URL           |                                            URL to `Loki` push api, should be like`${host}/loki/api/v1/push`                                            |                      URL |    -    | If you use `Loki` then ✅ |
+|        LOKI_TENANT_ID        |                                                Streams all components logs to `Loki`, see params below                                                 |          `true`, `false` |    -    | If you use `Loki` then ✅ |
+| TESTCONTAINERS_RYUK_DISABLED |                                   Testcontainers-Go reaper container, removes all the containers after the test exit                                   |          `true`, `false` | `false` |            🚫            |
+|         RESTY_DEBUG          |                                                            Log all Resty client HTTP calls                                                             |          `true`, `false` | `false` |            🚫            |
diff --git a/book/src/framework/connecting_chainlink_node.md b/book/src/framework/connecting_chainlink_node.md
@@ -0,0 +1,80 @@
+# Connecting Chainlink Node
+
+The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
+
+Let's spin up a simple component.
+
+
+Create your configuration in `smoke.toml`
+```toml
+[blockchain_a]
+  chain_id = "31337"
+  image = "ghcr.io/gakonst/foundry:latest"
+  port = "8545"
+  type = "anvil"
+
+[cl_node]
+  data_provider_url = "http://example.com"
+
+  [cl_node.db]
+    image = "postgres:15.6"
+    pull_image = true
+
+  [cl_node.node]
+    image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
+    pull_image = true
+```
+
+Create your test in `smoke_test.go`
+```golang
+
+package capabilities_test
+
+import (
+	"fmt"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/clnode"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+type Config struct {
+	BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+	CLNode      *clnode.Input     `toml:"cl_node" validate:"required"`
+}
+
+func TestNode(t *testing.T) {
+	in, err := framework.Load[Config](t)
+	require.NoError(t, err)
+
+	bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+	require.NoError(t, err)
+
+	networkCfg, err := clnode.NewNetworkCfgOneNetworkAllNodes(bc)
+	require.NoError(t, err)
+	in.CLNode.Node.TestConfigOverrides = networkCfg
+
+	output, err := clnode.NewNodeWithDB(in.CLNode)
+	require.NoError(t, err)
+
+	t.Run("test something", func(t *testing.T) {
+		fmt.Printf("node url: %s\n", output.Node.HostURL)
+		require.NotEmpty(t, output.Node.HostURL)
+	})
+}
+
+
+```
+
+Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
+```bash
+go test -v -run TestNode
+```
+
+Summary:
+- We defined configuration for `BlockchainNetwork` and `NodeWithDB` (Chainlink + PostgreSQL)
+- We connected them together by creating common network config in `NewNetworkCfgOneNetworkAllNodes`
+- We have a Chainlink node running, check `node url: ...` messages in logs to open UI
+
+You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)
diff --git a/book/src/framework/connecting_multiple_nodes.md b/book/src/framework/connecting_multiple_nodes.md
@@ -0,0 +1,80 @@
+# Writing your first test
+
+The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
+
+Let's spin up a simple component.
+
+
+Create your configuration in `smoke.toml`
+```toml
+[blockchain_a]
+  chain_id = "31337"
+  image = "ghcr.io/gakonst/foundry:latest"
+  port = "8545"
+  type = "anvil"
+
+[cl_node]
+  data_provider_url = "http://example.com"
+
+  [cl_node.db]
+    image = "postgres:15.6"
+    pull_image = true
+
+  [cl_node.node]
+    image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
+    pull_image = true
+```
+
+Create your test in `smoke_test.go`
+```golang
+
+package capabilities_test
+
+import (
+	"fmt"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/clnode"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+type Config struct {
+	BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+	CLNode      *clnode.Input     `toml:"cl_node" validate:"required"`
+}
+
+func TestNode(t *testing.T) {
+	in, err := framework.Load[Config](t)
+	require.NoError(t, err)
+
+	bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+	require.NoError(t, err)
+
+	networkCfg, err := clnode.NewNetworkCfgOneNetworkAllNodes(bc)
+	require.NoError(t, err)
+	in.CLNode.Node.TestConfigOverrides = networkCfg
+
+	output, err := clnode.NewNodeWithDB(in.CLNode)
+	require.NoError(t, err)
+
+	t.Run("test something", func(t *testing.T) {
+		fmt.Printf("node url: %s\n", output.Node.HostURL)
+		require.NotEmpty(t, output.Node.HostURL)
+	})
+}
+
+
+```
+
+Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
+```bash
+go test -v -run TestNode
+```
+
+Summary:
+- We defined configuration for `BlockchainNetwork` and `NodeWithDB` (Chainlink + PostgreSQL)
+- We connected them together by creating common network config in `NewNetworkCfgOneNetworkAllNodes`
+- We have a Chainlink node running, check `node url: ...` messages in logs to open UI
+
+You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)
diff --git a/book/src/framework/debugger.md b/book/src/framework/debugger.md
@@ -0,0 +1 @@
+# Debugger
diff --git a/book/src/framework/first_test.md b/book/src/framework/first_test.md
@@ -0,0 +1,55 @@
+# Writing your first test
+
+The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
+
+Let's spin up a simple component.
+
+Create your configuration in `smoke.toml`
+```toml
+[blockchain_a]
+  chain_id = "31337"
+  image = "ghcr.io/gakonst/foundry:latest"
+  port = "8545"
+  type = "anvil"
+```
+
+Create your test in `smoke_test.go`
+```golang
+package mymodule_test
+
+import (
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+type Config struct {
+	BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
+}
+
+func TestMe(t *testing.T) {
+	in, err := framework.Load[Config](t)
+	require.NoError(t, err)
+
+	bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
+	require.NoError(t, err)
+
+	t.Run("test something", func(t *testing.T) {
+		require.NotEmpty(t, bc.Nodes[0].HostHTTPUrl)
+	})
+}
+```
+
+Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
+```bash
+go test -v -run TestMe
+```
+
+Summary:
+- We defined configuration for `BlockchainNetwork`
+- We've used one CTF component in test and checked if it's working
+
+You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)
+
+Learn more about [anvil](./components/blockchains/anvil.md) component.