diff --git a/book/src/framework/components/chainlink/node.md b/book/src/framework/components/chainlink/node.md index 6d9836e17..4a949d022 100644 --- a/book/src/framework/components/chainlink/node.md +++ b/book/src/framework/components/chainlink/node.md @@ -1 +1,106 @@ # Node + +Here we provide *full* configuration parameters for `Node` + +<div class="warning"> +Here we provide full configuration reference, if you want to copy and run it, please remove all .out fields before! +</div> + + +## Configuration +```toml +[cl_node] + # Optional URL for fake data provider URL + # usually set up in test with local mock server + data_provider_url = "http://example.com" + + [cl_node.db] + # PostgreSQL image version and tag + image = "postgres:15.6" + # 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 = true + + [cl_node.node] + # A list of paths to capability binaries + capabilities = ["./capability_1", "./capability_2"] + # Default capabilities directory inside container + capabilities_container_dir = "/home/capabilities" + # Image to use, you can either provide "image" or "docker_file" + "docker_ctx" fields + image = "public.ecr.aws/chainlink/chainlink:v2.17.0" + # Path to your Chainlink Dockerfile + docker_file = "../../core/chainlink.Dockerfile" + # Path to docker context that should be used to build from + docker_ctx = "../.." + # Optional name for image we build, default is "ctftmp" + docker_image_name = "ctftmp" + # 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 = true + # Overrides Chainlink node TOML configuration + # can be multiline, see example + user_config_overrides = """ + [Log] + level = 'info' + """ + # Overrides Chainlink node secrets TOML configuration + # you can only add fields, overriding existing fields is prohibited by Chainlink node + user_secrets_overrides = """ + [AnotherSecret] + mySecret = 'a' + """ + + # Outputs are the results of deploying a component that can be used by another component + [cl_node.out] + # If 'use_cache' equals 'true' we skip component setup when we run the test and return the outputs + use_cache = true + # Describes deployed or external Chainlink node + [cl_node.out.node] + # Host Docker URLs the test uses + # in case of using external component you can replace these URLs with another deployment + p2p_url = "http://127.0.0.1:32812" + url = "http://127.0.0.1:32847" + + # Describes deployed or external Chainlink node + [cl_node.out.postgresql] + # PostgreSQL connection string + # in case of using external database can be overriden + url = "postgresql://chainlink:thispasswordislongenough@127.0.0.1:32846/chainlink?sslmode=disable" +``` + +## Usage +```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/clnode" + "github.com/stretchr/testify/require" + "testing" +) + +type Step2Cfg struct { + BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"` + CLNode *clnode.Input `toml:"cl_node" validate:"required"` +} + +func TestMe(t *testing.T) { + in, err := framework.Load[Step2Cfg](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) + }) +} +``` \ No newline at end of file diff --git a/book/src/framework/components/chainlink/nodeset.md b/book/src/framework/components/chainlink/nodeset.md index 81bb7a40e..2696b1ac0 100644 --- a/book/src/framework/components/chainlink/nodeset.md +++ b/book/src/framework/components/chainlink/nodeset.md @@ -1,6 +1,45 @@ # NodeSet +Here we provide *full* configuration parameters for `NodeSet` + +<div class="warning"> +Here we provide full configuration reference, if you want to copy and run it, please remove all .out fields before! +</div> + ## Configuration + +This component requires some Blockchain to be deployed, add this to config +```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 = "f4hrenh9it/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 + + # 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" +``` + +Then configure NodeSet ```toml [nodeset] # amount of Chainlink nodes to spin up @@ -13,7 +52,7 @@ [[nodeset.node_specs]] # Optional URL for fake data provider URL # usually set up in test with local mock server - data_provider_url = "" + data_provider_url = "http://example.com" [nodeset.node_specs.db] # PostgreSQL image version and tag @@ -79,27 +118,39 @@ ## Usage ```golang -package yourpackage_test +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/fake" ns "github.com/smartcontractkit/chainlink-testing-framework/framework/components/simple_node_set" "github.com/stretchr/testify/require" "testing" ) type Config struct { + BlockchainA *blockchain.Input `toml:"blockchain_a" validate:"required"` + MockerDataProvider *fake.Input `toml:"data_provider" validate:"required"` NodeSet *ns.Input `toml:"nodeset" validate:"required"` } -func TestNodeSet(t *testing.T) { +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) + dp, err := fake.NewFakeDataProvider(in.MockerDataProvider) + require.NoError(t, err) out, err := ns.NewSharedDBNodeSet(in.NodeSet, bc, dp.BaseURLDocker) require.NoError(t, err) - ... + t.Run("test something", func(t *testing.T) { + for _, n := range out.CLNodes { + require.NotEmpty(t, n.Node.HostURL) + require.NotEmpty(t, n.Node.HostP2PURL) + } + }) } ``` \ No newline at end of file diff --git a/book/src/framework/getting_started.md b/book/src/framework/getting_started.md index cc2aa6d49..97ff28bbd 100644 --- a/book/src/framework/getting_started.md +++ b/book/src/framework/getting_started.md @@ -6,18 +6,31 @@ ## Test setup -To start writing tests create a directory for your project with `go.mod` and pull the framework +To start writing tests create a directory for your project with `go.mod` and add a package ``` go get github.com/smartcontractkit/chainlink-testing-framework/framework ``` -Then download the CLI (runs from the directory where you have `go.mod`) +Download our [CLI](https://github.com/smartcontractkit/chainlink-testing-framework/releases/tag/framework%2Fv0.1.8) + +OS X `arm64` (M1/M2/M3 MacBooks) +``` +curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework%2F<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->/framework-<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->-darwin-arm64.tar.gz | tar -xz +``` + +OS X `amd64` (old Intel chips) +``` +curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework%2F<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->/framework-<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->-darwin-amd64.tar.gz | tar -xz +``` +Linux `arm64` +``` +curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework%2F<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->/framework-<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->-linux-arm64.tar.gz | tar -xz +``` + +Linux `amd64` ``` -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 +curl -L https://github.com/smartcontractkit/chainlink-testing-framework/releases/download/framework%2F<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->/framework-<!-- cmdrun git describe --tags --match "framework/v[0-9]*.[0-9]*.[0-9]*" --abbrev=0 | sed 's/^framework\///' -->-linux-amd64.tar.gz | tar -xz ``` -Or download a binary release [here](https://github.com/smartcontractkit/chainlink-testing-framework/releases/tag/framework%2Fv0.1.7) and rename it to `ctf` More CLI [docs](./cli.md) diff --git a/framework/.changeset/v0.1.9.md b/framework/.changeset/v0.1.9.md new file mode 100644 index 000000000..187bdb30f --- /dev/null +++ b/framework/.changeset/v0.1.9.md @@ -0,0 +1,2 @@ +- Simplify CLI download, generate URLs for every platform automatically +- Finalize Node and NodeSet docs \ No newline at end of file