Framework v0.1.1 (Docs) (#1242)

Framework v0.1.1 (Docs)

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: GH Pages Deploy (Docs, mdbook)
+
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.40'
+
+      - name: Install Pre-processors
+        run: |
+          cargo install mdbook-alerts
+          cargo install mdbook-cmdrun
+
+      - name: Build
+        working-directory: book
+        run: |
+          mdbook build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: book

.github/workflows/framework.yml

@@ -0,0 +1,41 @@
+name: Framework Docker Component Tests
+on:
+  push:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-framework
+  cancel-in-progress: true
+jobs:
+  test:
+    defaults:
+      run:
+        working-directory: framework
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
+      - name: Check for changes in Framework
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: changes
+        with:
+          filters: |
+            src:
+              - 'framework/**'
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: 1.22.8
+      - name: Cache Go modules
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: go-modules-${{ hashFiles('**/go.sum') }}-${{ runner.os }}-framework
+          restore-keys: |
+            go-modules-${{ hashFiles('**/go.sum') }}-${{ runner.os }}-framework
+      - name: Install dependencies
+        run: go mod download
+      - name: Run Docker Component Tests
+        if: steps.changes.outputs.src == 'true'
+        run: |
+          go test -timeout 5m -v -count 1 -run TestDocker ./...

README.md

@@ -1,39 +1,21 @@
 <div align="center">
 
 # Chainlink Testing Framework
+[![Documentation](https://img.shields.io/badge/Documentation-MDBook-blue?style=for-the-badge)](https://smartcontractkit.github.io/chainlink-testing-framework/overview.html)
 
-[![Main branch breaking changes check](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/rc-breaking-changes.yaml/badge.svg)](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/rc-breaking-changes.yaml)
+[//]: # ([![Main branch breaking changes check]&#40;https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/rc-breaking-changes.yaml/badge.svg&#41;]&#40;https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/rc-breaking-changes.yaml&#41;)
+[![Framework tag](https://img.shields.io/github/v/tag/smartcontractkit/chainlink-testing-framework?filter=%2Aframework%2A)](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
 [![Lib tag](https://img.shields.io/github/v/tag/smartcontractkit/chainlink-testing-framework?filter=%2Alib%2A)](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
 [![WASP tag](https://img.shields.io/github/v/tag/smartcontractkit/chainlink-testing-framework?filter=%2Awasp%2A)](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
 [![Seth tag](https://img.shields.io/github/v/tag/smartcontractkit/chainlink-testing-framework?filter=%2Aseth%2A)](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
 [![Havoc tag](https://img.shields.io/github/v/tag/smartcontractkit/chainlink-testing-framework?filter=%2Ahavoc%2A)](https://github.com/smartcontractkit/chainlink-testing-framework/tags)
-[![Go Report Card](https://goreportcard.com/badge/github.com/smartcontractkit/chainlink-testing-framework)](https://goreportcard.com/report/github.com/smartcontractkit/chainlink-testing-framework)
-[![Go Reference](https://pkg.go.dev/badge/github.com/smartcontractkit/chainlink-testing-framework.svg)](https://pkg.go.dev/github.com/smartcontractkit/chainlink-testing-framework/lib)
-![Go Version](https://img.shields.io/github/go-mod/go-version/smartcontractkit/chainlink-testing-framework?filename=./lib/go.mod)
+
 ![Tests](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/test.yaml/badge.svg)
 ![Lint](https://github.com/smartcontractkit/chainlink-testing-framework/actions/workflows/lint.yaml/badge.svg)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+[![Go Report Card](https://goreportcard.com/badge/github.com/smartcontractkit/chainlink-testing-framework)](https://goreportcard.com/report/github.com/smartcontractkit/chainlink-testing-framework)
+![Go Version](https://img.shields.io/github/go-mod/go-version/smartcontractkit/chainlink-testing-framework?filename=./lib/go.mod)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 </div>
 
-The Chainlink Testing Framework (CTF) is a blockchain development framework written in Go. Its primary purpose is to help chainlink developers create extensive integration, e2e, performance, and chaos tests to ensure the stability of the chainlink project. It can also be helpful to those who just want to use chainlink oracles in their projects to help test their contracts, or even for those that aren't using chainlink.
-
-If you're looking to implement a new chain integration for the testing framework, head over to the [blockchain](./blockchain/) directory for more info.
-
-# Content
-
-1. [Libraries](#libraries)
-2. [Releasing](#releasing)
-
-## Libraries
-
-CTF monorepository contains a set of libraries:
-
-- [Harness](lib/README.md) - Library to interact with different blockchains, create CL node jobs and use k8s and docker.
-- [WASP](wasp/README.md) - Scalable protocol-agnostic load testing library for `Go`
-- [Havoc](havoc/README.md) - Chaos testing library
-- [Seth](seth/README.md) - Ethereum client library with transaction tracing and gas bumping
-
-## Releasing
-
-We follow [SemVer](https://semver.org/) and follow best Go practices for releasing our modules, please follow the [instruction](RELEASE.md)
+The Chainlink Testing Framework (CTF) is a blockchain development framework written in Go. Its primary purpose is to help chainlink developers create extensive integration, e2e, performance, and chaos tests to ensure the stability of the chainlink project. It can also be helpful to those who just want to use chainlink oracles in their projects to help test their contracts, or even for those that aren't using chainlink.

book/Makefile

@@ -0,0 +1,3 @@
+.PHONY: run
+run:
+	mdbook serve -p 9999

book/README.md

@@ -0,0 +1,15 @@
+## MDBook
+Install [mdbook](https://github.com/rust-lang/mdBook)
+```
+cargo install mdbook && \
+cargo install mdbook-alerts && \
+cargo install mdbook-cmdrun
+```
+
+Run it locally
+```
+make run
+```
+Open your browser [here](http://localhost:9999/)
+
+GitHub hosted [version](https://smartcontractkit.github.io/chainlink-testing-framework/overview.html)

book/book.toml

@@ -0,0 +1,15 @@
+[book]
+authors = ["skudasov"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Chainlink Testing Framework"
+
+[build]
+build-dir = "docs"
+
+[output.html]
+default-theme = "ayu"
+
+[preprocessor.alerts]
+[preprocessor.cmdrun]

book/src/SUMMARY.md

@@ -0,0 +1,49 @@
+# Summary
+
+- [Overview](./overview.md)
+- [Framework](./framework/overview.md)
+    - [Getting Started](./framework/getting_started.md)
+    - [Your First Test](./framework/first_test.md)
+    - [Connecting Chainlink Node](./framework/connecting_chainlink_node.md)
+    - [Connecting Chainlink Node (Multiple networks)]()
+    - [NodeSet Environment](./framework/nodeset_environment.md)
+    - [NodeSet with Capabilities](./framework/nodeset_capabilities.md)
+    - [NodeSet with External Blockchain](./framework/nodeset_external.md)
+    - [NodeSet (Local Docker builds)](./framework/nodeset_docker_rebuild.md)
+    - [NodeSet Compat Environment](./framework/nodeset_compatibility.md)
+    - [CLI](./framework/cli.md)
+    - [Configuration](./framework/configuration.md)
+    - [Test Configuration](./framework/test_configuration_overrides.md)
+    - [Secrets]()
+    - [Observability Stack](framework/observability/observability_stack.md)
+      - [Metrics]()
+      - [Logs](framework/observability/logs.md)
+      - [Profiling](framework/observability/profiling.md)
+      - [Traces]()
+      - [Debugger]()
+    - [Components](framework/components/overview.md)
+        - [Blockchains](framework/components/blockchains/overview.md)
+            - [Anvil](framework/components/blockchains/anvil.md)
+            - [Geth]()
+            - [Optimism Stack]()
+            - [Arbitrum Stack]()
+        - [Chainlink]()
+          - [Node]()
+          - [NodeSet]()
+    - [Clients]()
+      - [Chainlink]()
+      - [RPC]()
+      - [Loki]()
+- [Libraries](./libraries.md)
+  - [Seth](./libs/seth.md)
+  - [WASP](./libs/wasp.md)
+  - [Havoc](./libs/havoc.md)
+
+---
+
+- [Developing](developing.md)
+  - [Components](developing/developing_components.md)
+- [Releasing modules](releasing_modules.md)
+
+---
+- [Build info](build_info.md)

book/src/build_info.md

@@ -0,0 +1,5 @@
+# Build info
+
+This documentation was generated from:
+- Branch `<!-- cmdrun git rev-parse --abbrev-ref HEAD -->`
+- Commit: `<!-- cmdrun  git rev-parse --short HEAD -->`

book/src/developing.md

@@ -0,0 +1,8 @@
+# Developing
+
+Here we describe good practices for developing components for our framework.
+
+Rules for components are simple:
+- Component should declare some `Input` and an optional `Output` (we use that so we can skip or cache any component results)
+- Components should be isolated, they should not return anything except basic types like `int`, `string`, `maps` or `structs`
+- Component **must** have documentation under [Components](./framework/components/overview.md), here is an [example](./framework/components/blockchains/anvil.md)

book/src/developing/developing_components.md

@@ -0,0 +1,96 @@
+## Developing Components
+
+To build a scalable framework that enables the reuse of our product deployments (contracts or services in Docker), we need to establish a clear component structure.
+
+```golang
+package mycomponent
+
+import (
+	"fmt"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+)
+
+type Input struct {
+    // inputs fields that component exposes for configuration
+    ...
+    // outputs are embedded into inputs so framework can automatically save them
+	Out                      *Output  `toml:"out"`
+}
+
+type Output struct {
+    UseCache bool             `toml:"use_cache"`
+    // outputs that will be dumped to config and cached
+}
+
+
+func NewComponent(input *Input) (*Output, error) {
+	if input.Out != nil && input.Out.UseCache {
+		return input.Out, nil
+	}
+
+	// component logic here
+	// deploy a docker container(s)
+	// or deploy a set of smart contracts
+
+	input.Out = &Output{
+	    UseCache: true,
+	    // other fields
+	    ...
+	}
+	return out, nil
+}
+```
+
+Each component can define inputs and outputs, following these rules:
+
+- Outputs should be included within inputs.
+- If your component is used for side effects output can be omitted.
+- `input.Out.UseCache` should be added if you'd like to use caching, see more [here](caching)
+
+### Docker components good practices for [testcontainers-go](https://golang.testcontainers.org/):
+
+An example [simple component](../../../../framework/components/blockchain/anvil.go)
+
+An example of [complex component](../../../../framework/components/clnode/clnode.go)
+
+An example of [composite component](../../../../framework/components/simple_node_set/node_set.go)
+
+- Inputs should include at least `image`, `tag` and `pull_image` field
+```golang
+	Image                string `toml:"image" validate:"required"`
+	Tag                  string `toml:"tag" validate:"required"`
+	PullImage            bool   `toml:"pull_image" validate:"required"`
+```
+
+- `ContainerRequest` must contain labels, network and alias required for local observability stack and deployment isolation
+```golang
+		Labels:   framework.DefaultTCLabels(),
+		Networks: []string{framework.DefaultNetworkName},
+		NetworkAliases: map[string][]string{
+			framework.DefaultNetworkName: {containerName},
+		},
+```
+- In order to copy files into container use `framework.WriteTmpFile(data string, fileName string)`
+```golang
+	userSecretsOverridesFile, err := WriteTmpFile(in.Node.UserSecretsOverrides, "user-secrets-overrides.toml")
+	if err != nil {
+		return nil, err
+	}
+```
+- Output of docker component must contain all the URLs component exposes for access, both for internal docker usage and external test (host) usage
+```golang
+	host, err := framework.GetHost(c)
+	if err != nil {
+		return nil, err
+	}
+	mp, err := c.MappedPort(ctx, nat.Port(bindPort))
+	if err != nil {
+		return nil, err
+	}
+
+	return &NodeOut{
+	    UseCache: true,
+		DockerURL: fmt.Sprintf("http://%s:%s", containerName, in.Node.Port),
+		HostURL:   fmt.Sprintf("http://%s:%s", host, mp.Port()),
+	}, nil
+```

book/src/framework.md

@@ -0,0 +1 @@
+# Framework

book/src/framework/cli.md

@@ -0,0 +1,6 @@
+## CLI
+
+To keep documentation simple we provide CLI docs in "help" format
+```
+ctf -h
+```