Skip to content

Commit 4764f4e

Browse files
skudasovskudasov
committed
v2 docs
1 parent 112a680 commit 4764f4e

File tree

16 files changed

+404
-55
lines changed

16 files changed

+404
-55
lines changed

‎book/src/SUMMARY.md‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,29 @@
11
# Summary
22

33
- [Overview](./overview.md)
4-
- [Libraries](./libraries.md)
5-
- [Seth](./libs/seth.md)
6-
- [WASP](./libs/wasp.md)
7-
- [Havoc](./libs/havoc.md)
84
- [Framework](./framework/overview.md)
5+
- [Overview](./framework/overview.md)
96
- [Getting Started](./framework/getting_started.md)
7+
- [First Test](./framework/first_test.md)
8+
- [Connecting Chainlink Node](./framework/connecting_chainlink_node.md)
9+
- [Connecting Chainlink Node (Multiple networks)]()
10+
- [Basic NodeSet Environment](./framework/basic_environment.md)
1011
- [CLI](./framework/cli.md)
12+
- [Configuration](./framework/configuration.md)
13+
- [Observability Stack](framework/observability_stack.md)
14+
- [Metrics]()
15+
- [Logs](framework/logs.md)
16+
- [Profiling](framework/profiling.md)
17+
- [Traces]()
18+
- [Debugger]()
1119
- [Components](framework/components/overview.md)
12-
- [Blockchains](framework/components/blockchains/overview.md)
13-
- [Anvil](framework/components/blockchains/anvil.md)
20+
- [Blockchains](framework/components/blockchains/overview.md)
21+
- [Anvil](framework/components/blockchains/anvil.md)
1422
- [Secrets](./secrets.md)
23+
- [Libraries](./libraries.md)
24+
- [Seth](./libs/seth.md)
25+
- [WASP](./libs/wasp.md)
26+
- [Havoc](./libs/havoc.md)
1527

1628
---
1729

‎book/src/framework/basic_environment.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Chainlink Cluster (NodeSet) Environment Test
2+
3+
Create a configuration file `smoke.toml`
4+
```toml
5+
funds_eth = 30.0
6+
7+
[blockchain_a]
8+
chain_id = "31337"
9+
image = "f4hrenh9it/foundry:latest"
10+
port = "8545"
11+
type = "anvil"
12+
13+
[contracts]
14+
15+
[data_provider]
16+
port = 9111
17+
18+
[nodeset]
19+
nodes = 5
20+
override_mode = "all"
21+
22+
[[nodeset.node_specs]]
23+
24+
[nodeset.node_specs.db]
25+
image = "postgres:15.6"
26+
pull_image = true
27+
28+
[nodeset.node_specs.node]
29+
image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
30+
pull_image = true
31+
32+
```
33+
34+
Create a file `smoke_test.go`
35+
```golang
36+
package yourpackage_test
37+
38+
import (
39+
"fmt"
40+
"github.com/smartcontractkit/chainlink-testing-framework/framework"
41+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
42+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/fake"
43+
ns "github.com/smartcontractkit/chainlink-testing-framework/framework/components/simple_node_set"
44+
"github.com/smartcontractkit/chainlink/e2e/capabilities/components/onchain"
45+
"github.com/stretchr/testify/require"
46+
"testing"
47+
)
48+
49+
type Config struct {
50+
FundingETH float64 `toml:"funds_eth"`
51+
BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
52+
Contracts *onchain.Input `toml:"contracts" validate:"required"`
53+
MockerDataProvider *fake.Input `toml:"data_provider" validate:"required"`
54+
NodeSet *ns.Input `toml:"nodeset" validate:"required"`
55+
}
56+
57+
func TestNodeSet(t *testing.T) {
58+
in, err := framework.Load[Config](t)
59+
require.NoError(t, err)
60+
61+
// deploy docker test environment
62+
bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
63+
require.NoError(t, err)
64+
dp, err := fake.NewFakeDataProvider(in.MockerDataProvider)
65+
require.NoError(t, err)
66+
out, err := ns.NewSharedDBNodeSet(in.NodeSet, bc, dp.BaseURLDocker)
67+
require.NoError(t, err)
68+
}
69+
```
70+
71+
Run it
72+
```bash
73+
go test -v -run TestNodeSet
74+
```
75+

‎book/src/framework/cli.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,6 @@
11
## CLI
2-
### Install
3-
```
4-
go get github.com/smartcontractkit/chainlink-testing-framework/framework/cmd && \
5-
go install github.com/smartcontractkit/chainlink-testing-framework/framework/cmd && \
6-
mv ~/go/bin/cmd ~/go/bin/ctf
7-
```
8-
### Usage
2+
3+
To keep documentation simple we provide CLI docs in "help" format
94
```
105
ctf -h
116
```

‎book/src/framework/components/blockchains/anvil.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,33 @@
11
# Anvil
22
[Anvil](https://book.getfoundry.sh/anvil/) is a Foundry local EVM blockchain simulator
33

4-
Use `docker_cmd_params = ['--block-time=1', '...']` to provide more params
5-
64
## Configuration
75
```toml
86
[blockchain_a]
7+
# Blockchain node type, can be "anvil" or "geth"
8+
type = "anvil"
9+
# Chain ID
910
chain_id = "31337"
11+
# Anvil command line params, ex.: docker_cmd_params = ['--block-time=1', '...']
1012
docker_cmd_params = []
13+
# Docker image and tag
1114
image = "ghcr.io/gakonst/foundry:latest"
15+
# External port to expose
1216
port = "8545"
17+
# Pulls the image every time if set to 'true', used like that in CI. Can be set to 'false' to speed up local runs
1318
pull_image = false
14-
type = "anvil"
1519

20+
# Outputs are the results of deploying a component that can be used by another component
1621
[blockchain_a.out]
1722
chain_id = "31337"
23+
# If 'use_cache' equals 'true' we skip component setup when we run the test and return the outputs
1824
use_cache = true
1925

2026
[[blockchain_a.out.nodes]]
27+
# URLs to access the node(s) inside docker network, used by other components
2128
docker_internal_http_url = "http://anvil-14411:8545"
2229
docker_internal_ws_url = "ws://anvil-14411:8545"
30+
# URLs to access the node(s) on your host machine or in CI
2331
http_url = "http://127.0.0.1:33955"
2432
ws_url = "ws://127.0.0.1:33955"
2533
```

‎book/src/framework/configuration.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Configuration
2+
3+
### Environment variables
4+
| Name | Description | Possible values | Default | Required? |
5+
|:----------------------------:|:------------------------------------------------------------------------------------------------------------------------------------------------------:|-------------------------:|:-------:|:------------------------:|
6+
| 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 | | ✅ |
7+
| CTF_LOG_LEVEL | Harness log level | `info`, `debug`, `trace` | `info` | 🚫 |
8+
| CTF_LOKI_STREAM | Streams all components logs to `Loki`, see params below | `true`, `false` | `false` | 🚫 |
9+
| LOKI_URL | URL to `Loki` push api, should be like`${host}/loki/api/v1/push` | URL | - | If you use `Loki` then ✅ |
10+
| LOKI_TENANT_ID | Streams all components logs to `Loki`, see params below | `true`, `false` | - | If you use `Loki` then ✅ |
11+
| TESTCONTAINERS_RYUK_DISABLED | Testcontainers-Go reaper container, removes all the containers after the test exit | `true`, `false` | `false` | 🚫 |
12+
| RESTY_DEBUG | Log all Resty client HTTP calls | `true`, `false` | `false` | 🚫 |

‎book/src/framework/connecting_chainlink_node.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Connecting Chainlink Node
2+
3+
The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
4+
5+
Let's spin up a simple component.
6+
7+
8+
Create your configuration in `smoke.toml`
9+
```toml
10+
[blockchain_a]
11+
chain_id = "31337"
12+
image = "ghcr.io/gakonst/foundry:latest"
13+
port = "8545"
14+
type = "anvil"
15+
16+
[cl_node]
17+
data_provider_url = "http://example.com"
18+
19+
[cl_node.db]
20+
image = "postgres:15.6"
21+
pull_image = true
22+
23+
[cl_node.node]
24+
image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
25+
pull_image = true
26+
```
27+
28+
Create your test in `smoke_test.go`
29+
```golang
30+
31+
package capabilities_test
32+
33+
import (
34+
"fmt"
35+
"github.com/smartcontractkit/chainlink-testing-framework/framework"
36+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
37+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/clnode"
38+
"github.com/stretchr/testify/require"
39+
"testing"
40+
)
41+
42+
type Config struct {
43+
BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
44+
CLNode *clnode.Input `toml:"cl_node" validate:"required"`
45+
}
46+
47+
func TestNode(t *testing.T) {
48+
in, err := framework.Load[Config](t)
49+
require.NoError(t, err)
50+
51+
bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
52+
require.NoError(t, err)
53+
54+
networkCfg, err := clnode.NewNetworkCfgOneNetworkAllNodes(bc)
55+
require.NoError(t, err)
56+
in.CLNode.Node.TestConfigOverrides = networkCfg
57+
58+
output, err := clnode.NewNodeWithDB(in.CLNode)
59+
require.NoError(t, err)
60+
61+
t.Run("test something", func(t *testing.T) {
62+
fmt.Printf("node url: %s\n", output.Node.HostURL)
63+
require.NotEmpty(t, output.Node.HostURL)
64+
})
65+
}
66+
67+
68+
```
69+
70+
Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
71+
```bash
72+
go test -v -run TestNode
73+
```
74+
75+
Summary:
76+
- We defined configuration for `BlockchainNetwork` and `NodeWithDB` (Chainlink + PostgreSQL)
77+
- We connected them together by creating common network config in `NewNetworkCfgOneNetworkAllNodes`
78+
- We have a Chainlink node running, check `node url: ...` messages in logs to open UI
79+
80+
You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)

‎book/src/framework/connecting_multiple_nodes.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Writing your first test
2+
3+
The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
4+
5+
Let's spin up a simple component.
6+
7+
8+
Create your configuration in `smoke.toml`
9+
```toml
10+
[blockchain_a]
11+
chain_id = "31337"
12+
image = "ghcr.io/gakonst/foundry:latest"
13+
port = "8545"
14+
type = "anvil"
15+
16+
[cl_node]
17+
data_provider_url = "http://example.com"
18+
19+
[cl_node.db]
20+
image = "postgres:15.6"
21+
pull_image = true
22+
23+
[cl_node.node]
24+
image = "public.ecr.aws/chainlink/chainlink:v2.17.0"
25+
pull_image = true
26+
```
27+
28+
Create your test in `smoke_test.go`
29+
```golang
30+
31+
package capabilities_test
32+
33+
import (
34+
"fmt"
35+
"github.com/smartcontractkit/chainlink-testing-framework/framework"
36+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
37+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/clnode"
38+
"github.com/stretchr/testify/require"
39+
"testing"
40+
)
41+
42+
type Config struct {
43+
BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
44+
CLNode *clnode.Input `toml:"cl_node" validate:"required"`
45+
}
46+
47+
func TestNode(t *testing.T) {
48+
in, err := framework.Load[Config](t)
49+
require.NoError(t, err)
50+
51+
bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
52+
require.NoError(t, err)
53+
54+
networkCfg, err := clnode.NewNetworkCfgOneNetworkAllNodes(bc)
55+
require.NoError(t, err)
56+
in.CLNode.Node.TestConfigOverrides = networkCfg
57+
58+
output, err := clnode.NewNodeWithDB(in.CLNode)
59+
require.NoError(t, err)
60+
61+
t.Run("test something", func(t *testing.T) {
62+
fmt.Printf("node url: %s\n", output.Node.HostURL)
63+
require.NotEmpty(t, output.Node.HostURL)
64+
})
65+
}
66+
67+
68+
```
69+
70+
Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
71+
```bash
72+
go test -v -run TestNode
73+
```
74+
75+
Summary:
76+
- We defined configuration for `BlockchainNetwork` and `NodeWithDB` (Chainlink + PostgreSQL)
77+
- We connected them together by creating common network config in `NewNetworkCfgOneNetworkAllNodes`
78+
- We have a Chainlink node running, check `node url: ...` messages in logs to open UI
79+
80+
You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)

‎book/src/framework/debugger.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Debugger

‎book/src/framework/first_test.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Writing your first test
2+
3+
The Chainlink Testing Framework (CTF) is a modular, data-driven tool that lets you explicitly define and configure various Chainlink components.
4+
5+
Let's spin up a simple component.
6+
7+
Create your configuration in `smoke.toml`
8+
```toml
9+
[blockchain_a]
10+
chain_id = "31337"
11+
image = "ghcr.io/gakonst/foundry:latest"
12+
port = "8545"
13+
type = "anvil"
14+
```
15+
16+
Create your test in `smoke_test.go`
17+
```golang
18+
package mymodule_test
19+
20+
import (
21+
"github.com/smartcontractkit/chainlink-testing-framework/framework"
22+
"github.com/smartcontractkit/chainlink-testing-framework/framework/components/blockchain"
23+
"github.com/stretchr/testify/require"
24+
"testing"
25+
)
26+
27+
type Config struct {
28+
BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"`
29+
}
30+
31+
func TestMe(t *testing.T) {
32+
in, err := framework.Load[Config](t)
33+
require.NoError(t, err)
34+
35+
bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
36+
require.NoError(t, err)
37+
38+
t.Run("test something", func(t *testing.T) {
39+
require.NotEmpty(t, bc.Nodes[0].HostHTTPUrl)
40+
})
41+
}
42+
```
43+
44+
Select your configuration by setting `CTF_CONFIGS=smoke.toml` and run it
45+
```bash
46+
go test -v -run TestMe
47+
```
48+
49+
Summary:
50+
- We defined configuration for `BlockchainNetwork`
51+
- We've used one CTF component in test and checked if it's working
52+
53+
You can learn more about [component design](./components/overview.md) or proceed with another example of [connecting Chainlink node](./connecting_chainlink_node.md)
54+
55+
Learn more about [anvil](./components/blockchains/anvil.md) component.

0 commit comments

Comments
 (0)