add blockscout, refactor CLI

Author: skudasov

book/src/SUMMARY.md

@@ -22,6 +22,7 @@
       - [Profiling](framework/observability/profiling.md)
       - [Traces]()
       - [Debugger]()
+    - [Blockscout](framework/observability/blockscout.md)
     - [Components](framework/components/overview.md)
         - [Blockchains](framework/components/blockchains/overview.md)
             - [Anvil](framework/components/blockchains/anvil.md)

book/src/framework.md

@@ -1,5 +1,7 @@
 # Getting started
 
+## Test setup
+
 To start writing tests create a directory for your project with `go.mod` and pull the framework
 ```
 go get github.com/smartcontractkit/chainlink-testing-framework/framework
@@ -14,12 +16,6 @@ mv ~/go/bin/cmd ~/go/bin/ctf
 ```
 More CLI [docs](./cli.md)
 
-
-Spin up your local obserability stack
-```
-ctf obs up
-```
-
 Create an `.envrc` file and put common parameters there (you can use [direnv](https://direnv.net/) to sync them more easily)
 ```
 export CTF_LOG_LEVEL=info
@@ -30,4 +26,18 @@ export CTF_CONFIGS=smoke.toml
 export PRIVATE_KEY="ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
 ```
 
-Now you are ready to write your [first test](./first_test.md)
+Now you are ready to write your [first test](./first_test.md)
+
+## Tools setup (Optional)
+
+This setup is optional, and it explains how to setup a local observability stack for on-chain and off-chain components.
+
+Spin up your local obserability stack (Grafana LGTM)
+```
+ctf obs up
+```
+
+Spin up your `Blockscout` stack
+```
+ctf bs up
+```

book/src/framework/getting_started.md

@@ -0,0 +1,25 @@
+# Blockscout
+
+You can use local [Blockscout](https://www.blockscout.com/) instance to debug EVM smart contracts.
+
+```
+ctf bs up
+```
+Your `Blockscout` instance is up on [localhost](http://localhost)
+
+To remove it, we also clean up all Blockscout databases to prevent stale data when restarting your tests.
+```
+ctf bs down
+```
+
+<div class="warning">
+
+Blockscout isn’t ideal for local, ephemeral environments, as it won’t re-index blocks and transactions on test reruns. The easiest approach is to set up Blockscout first, initialize the test environment, switch to the [cache](../components/caching.md) config, and run tests without restarting RPC nodes. 
+
+Otherwise, use `ctf bs r` each time you restart your test with a fresh docker environment.
+</div>
+
+<div class="warning">
+
+Blockscout integration is still WIP, for now Blockscout reads only one node that is on `:8545`, all our blockchain implementation expose this port by default.
+</div>

book/src/framework/observability/blockscout.md

@@ -2,10 +2,16 @@
 
 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.
+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.
 
+This documentation is for:
+- Developers looking to write end-to-end tests
+- Quality Assurance Engineers aiming to test locally
+
+To get started with writing tests, refer to the [Framework](./framework/getting_started.md) chapter, where we guide you from basic to more complex scenarios.
+
 [Repository](https://github.com/smartcontractkit/chainlink-testing-framework) contains two major pieces:
 - [Framework](framework/overview.md)
 - [Libraries](libraries.md)

book/src/overview.md

@@ -0,0 +1,4 @@
+blockscout/services/blockscout-db-data
+blockscout/services/logs
+blockscout/services/redis-data
+blockscout/services/stats-db-data

framework/cmd/.gitignore

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"fmt"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"path/filepath"
+)
+
+func blockscoutUp() error {
+	framework.L.Info().Msg("Creating local Blockscout stack")
+	if err := extractAllFiles("observability"); err != nil {
+		return err
+	}
+	err := runCommand("bash", "-c", fmt.Sprintf(`
+		cd %s && \
+		docker compose up -d
+	`, "blockscout"))
+	if err != nil {
+		return err
+	}
+	framework.L.Info().Msg("Done")
+	fmt.Println()
+	framework.L.Info().Msgf("Blockscout is up at: %s", "http://localhost")
+	return nil
+}
+
+func blockscoutDown() error {
+	framework.L.Info().Msg("Removing local Blockscout stack")
+	err := runCommand("bash", "-c", fmt.Sprintf(`
+		cd %s && \
+		docker compose down -v
+	`, "blockscout"))
+	if err != nil {
+		return err
+	}
+	err = runCommand("bash", "-c", fmt.Sprintf(`
+		cd %s && \
+		rm -rf blockscout-db-data && \
+		rm -rf logs && \
+		rm -rf redis-data && \
+		rm -rf stats-db-data
+	`, filepath.Join("blockscout", "services")))
+	framework.L.Info().Msg("Done")
+	return nil
+}

framework/cmd/blockscout.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"fmt"
+	"github.com/rs/zerolog"
+	"github.com/smartcontractkit/chainlink-testing-framework/framework"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+func cleanDockerResources() error {
+	framework.L.Info().Str("label", "framework=ctf").Msg("Cleaning up docker containers")
+	// Bash command for removing Docker containers and networks with "framework=ctf" label
+	cmd := exec.Command("bash", "-c", `
+		docker ps -aq --filter "label=framework=ctf" | xargs -r docker rm -f && \
+		docker network ls --filter "label=framework=ctf" -q | xargs -r docker network rm
+	`)
+	framework.L.Debug().Msg("Running command")
+	if framework.L.GetLevel() == zerolog.DebugLevel {
+		fmt.Println(cmd.String())
+	}
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("error running clean command: %s", string(output))
+	}
+	framework.L.Info().Msgf("Done")
+	return nil
+}
+
+// BuildDocker runs Docker commands to set up a local registry, build an image, and push it.
+func BuildDocker(dockerfile string, buildContext string, imageName string) error {
+	registryRunning := isContainerRunning("local-registry")
+	if registryRunning {
+		fmt.Println("Local registry container is already running.")
+	} else {
+		framework.L.Info().Msg("Starting local registry container...")
+		err := runCommand("docker", "run", "-d", "-p", "5050:5000", "--name", "local-registry", "registry:2")
+		if err != nil {
+			return fmt.Errorf("failed to start local registry: %w", err)
+		}
+		framework.L.Info().Msg("Local registry started")
+	}
+
+	img := fmt.Sprintf("localhost:5050/%s:latest", imageName)
+	framework.L.Info().Str("DockerFile", dockerfile).Str("Context", buildContext).Msg("Building Docker image")
+	err := runCommand("docker", "build", "-t", fmt.Sprintf("localhost:5050/%s:latest", imageName), "-f", dockerfile, buildContext)
+	if err != nil {
+		return fmt.Errorf("failed to build Docker image: %w", err)
+	}
+	framework.L.Info().Msg("Docker image built successfully")
+
+	framework.L.Info().Str("Image", img).Msg("Pushing Docker image to local registry")
+	fmt.Println("Pushing Docker image to local registry...")
+	err = runCommand("docker", "push", img)
+	if err != nil {
+		return fmt.Errorf("failed to push Docker image: %w", err)
+	}
+	framework.L.Info().Msg("Docker image pushed successfully")
+	return nil
+}
+
+// isContainerRunning checks if a Docker container with the given name is running.
+func isContainerRunning(containerName string) bool {
+	cmd := exec.Command("docker", "ps", "--filter", fmt.Sprintf("name=%s", containerName), "--format", "{{.Names}}")
+	output, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+	return strings.Contains(string(output), containerName)
+}
+
+// runCommand executes a command and prints the output.
+func runCommand(name string, args ...string) error {
+	cmd := exec.Command(name, args...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}