Skip to content

Commit 444ccab

Browse files
sebawosebawo
committed
docs: add comprehensive GitHub wiki (Deep Wiki style) with advanced examples, reference, and contributing guides
1 parent 5714c5e commit 444ccab

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+17011
-0
lines changed

‎Contributing/Overview.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Contributing Guide
2+
3+
Thank you for your interest in contributing to the Chainlink Testing Framework (CTF)! We welcome contributions from the community to improve the framework, add features, fix bugs, and enhance documentation.
4+
5+
---
6+
7+
## How to Contribute
8+
9+
1. **Fork the repository** and create your branch from `main`.
10+
2. **Open an issue** to discuss your proposed change if it's non-trivial.
11+
3. **Write clear, maintainable code** and add tests for new features or bug fixes.
12+
4. **Document your changes** in the code and/or wiki as appropriate.
13+
5. **Open a Pull Request (PR)** with a clear description of your changes and link to any relevant issues.
14+
6. **Participate in code review** and address feedback promptly.
15+
16+
---
17+
18+
## Code of Conduct
19+
20+
We are committed to fostering a welcoming and inclusive environment. Please read and follow our [Code of Conduct](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/CODE_OF_CONDUCT.md).
21+
22+
---
23+
24+
## Development Setup
25+
26+
1. **Clone the repository**
27+
```bash
28+
git clone https://github.com/smartcontractkit/chainlink-testing-framework.git
29+
cd chainlink-testing-framework
30+
```
31+
2. **Install dependencies**
32+
- [Go](https://go.dev/doc/install) 1.21+
33+
- [Docker](https://www.docker.com/)
34+
- [direnv](https://direnv.net/) (optional, for environment management)
35+
- [nix](https://nixos.org/manual/nix/stable/installation/installation.html) (optional, for dev environments)
36+
3. **Set up your environment**
37+
```bash
38+
cp Getting-Started/Installation.md .
39+
# Follow the installation instructions for your OS
40+
```
41+
4. **Run tests locally**
42+
```bash
43+
CTF_CONFIGS=smoke.toml go test -v
44+
```
45+
5. **Lint and format your code**
46+
```bash
47+
go fmt ./...
48+
go vet ./...
49+
golangci-lint run
50+
```
51+
52+
---
53+
54+
## Pull Request Process
55+
56+
1. **Open a draft PR** early to get feedback.
57+
2. **Ensure all tests pass** and code is linted.
58+
3. **Describe your changes** clearly in the PR description.
59+
4. **Link to any related issues** (e.g., `Closes #123`).
60+
5. **Request review** from maintainers or relevant code owners.
61+
6. **Address review comments** and update your PR as needed.
62+
7. **Wait for approval and merge** (maintainers will handle merging).
63+
64+
---
65+
66+
## Getting Help
67+
68+
- **Search issues**: [GitHub Issues](https://github.com/smartcontractkit/chainlink-testing-framework/issues)
69+
- **Ask in discussions**: [GitHub Discussions](https://github.com/smartcontractkit/chainlink-testing-framework/discussions)
70+
- **Open a new issue** for bugs, feature requests, or questions
71+
- **Contact maintainers** via GitHub if you need further assistance
72+
73+
---
74+
75+
## Resources
76+
- [Home](../Home)
77+
- [Installation Guide](../Getting-Started/Installation)
78+
- [API Reference](../Reference/API-Reference)
79+
- [Troubleshooting](../Reference/Troubleshooting)
80+
- [Code of Conduct](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/CODE_OF_CONDUCT.md)
81+
- [LICENSE](https://github.com/smartcontractkit/chainlink-testing-framework/blob/main/LICENSE)

‎Examples/Advanced-Examples.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Advanced Examples
2+
3+
This page provides advanced and real-world test scenarios using the Chainlink Testing Framework (CTF). These examples demonstrate how to leverage CTF for complex, production-like workflows.
4+
5+
---
6+
7+
## 1. Multi-Chain Integration Test
8+
9+
Test a system that interacts with multiple blockchains (e.g., Ethereum and Solana) and verifies cross-chain data flow.
10+
11+
```toml
12+
[ethereum]
13+
type = "geth"
14+
image = "ethereum/client-go"
15+
tag = "v1.12.0"
16+
pull_image = true
17+
18+
[solana]
19+
type = "solana"
20+
image = "solanalabs/solana"
21+
tag = "v1.16.0"
22+
pull_image = true
23+
24+
[chainlink_node]
25+
image = "public.ecr.aws/chainlink/chainlink"
26+
tag = "2.7.0"
27+
pull_image = true
28+
```
29+
30+
```go
31+
func TestMultiChainIntegration(t *testing.T) {
32+
type Config struct {
33+
Ethereum *blockchain.Input `toml:"ethereum" validate:"required"`
34+
Solana *blockchain.Input `toml:"solana" validate:"required"`
35+
ChainlinkNode *clnode.Input `toml:"chainlink_node" validate:"required"`
36+
}
37+
in, err := framework.Load[Config](t)
38+
require.NoError(t, err)
39+
eth, err := blockchain.NewBlockchainNetwork(in.Ethereum)
40+
require.NoError(t, err)
41+
sol, err := blockchain.NewBlockchainNetwork(in.Solana)
42+
require.NoError(t, err)
43+
cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
44+
require.NoError(t, err)
45+
// ... deploy contracts, set up jobs, verify cross-chain data
46+
}
47+
```
48+
49+
---
50+
51+
## 2. Upgrade and Migration Test
52+
53+
Test that a Chainlink node or contract can be upgraded without breaking existing functionality.
54+
55+
```toml
56+
[chainlink_node]
57+
image = "public.ecr.aws/chainlink/chainlink"
58+
tag = "2.6.0"
59+
pull_image = true
60+
```
61+
62+
```go
63+
func TestUpgrade(t *testing.T) {
64+
// Deploy with old version
65+
in, err := framework.Load[Config](t)
66+
require.NoError(t, err)
67+
cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
68+
require.NoError(t, err)
69+
// ... run smoke test
70+
71+
// Upgrade node
72+
in.ChainlinkNode.Tag = "2.7.0"
73+
clUpgraded, err := clnode.NewChainlinkNode(in.ChainlinkNode)
74+
require.NoError(t, err)
75+
// ... verify data, jobs, and state are preserved
76+
}
77+
```
78+
79+
---
80+
81+
## 3. Chaos Engineering Test
82+
83+
Inject failures and network issues to test system resilience using Havoc.
84+
85+
```go
86+
func TestChaosResilience(t *testing.T) {
87+
in, err := framework.Load[Config](t)
88+
require.NoError(t, err)
89+
cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
90+
require.NoError(t, err)
91+
// Start chaos experiment
92+
client, err := havoc.NewClient()
93+
require.NoError(t, err)
94+
chaos, err := havoc.NewChaos(client, createNetworkChaos())
95+
require.NoError(t, err)
96+
err = chaos.Create(context.Background())
97+
require.NoError(t, err)
98+
// ... run test logic while chaos is active
99+
chaos.Delete(context.Background())
100+
}
101+
```
102+
103+
---
104+
105+
## 4. Performance and Load Test
106+
107+
Use WASP to generate load and measure system performance under stress.
108+
109+
```go
110+
func TestPerformance(t *testing.T) {
111+
profile := wasp.NewProfile()
112+
generator := wasp.NewGenerator(&wasp.Config{
113+
T: 60 * time.Second,
114+
RPS: 100,
115+
LoadType: wasp.RPS,
116+
Schedule: wasp.Plain(100, 60*time.Second),
117+
})
118+
generator.AddRequestFn(func(ctx context.Context) error {
119+
// Simulate contract call or API request
120+
return nil
121+
})
122+
profile.Add(generator)
123+
_, err := profile.Run(true)
124+
require.NoError(t, err)
125+
}
126+
```
127+
128+
---
129+
130+
## 5. End-to-End Oracle Test
131+
132+
Test the full workflow from contract deployment to job fulfillment and data reporting.
133+
134+
```go
135+
func TestOracleE2E(t *testing.T) {
136+
in, err := framework.Load[Config](t)
137+
require.NoError(t, err)
138+
bc, err := blockchain.NewBlockchainNetwork(in.BlockchainA)
139+
require.NoError(t, err)
140+
cl, err := clnode.NewChainlinkNode(in.ChainlinkNode)
141+
require.NoError(t, err)
142+
// Deploy oracle contract
143+
// Register job on Chainlink node
144+
// Send request and verify fulfillment
145+
}
146+
```
147+
148+
---
149+
150+
## 6. Real-World: Staging Environment Reuse
151+
152+
Reuse cached components and substitute staging URLs for persistent environment testing.
153+
154+
```toml
155+
[blockchain_a]
156+
type = "anvil"
157+
use_cache = true
158+
external_url = "https://staging-eth.example.com"
159+
160+
[chainlink_node]
161+
use_cache = true
162+
external_url = "https://staging-cl.example.com"
163+
```
164+
165+
```go
166+
func TestStagingReuse(t *testing.T) {
167+
in, err := framework.Load[Config](t)
168+
require.NoError(t, err)
169+
// Use staging URLs for integration tests
170+
}
171+
```
172+
173+
---
174+
175+
## More Examples
176+
- [WASP Load Testing](../Libraries/WASP)
177+
- [Havoc Chaos Testing](../Libraries/Havoc)
178+
- [Seth Ethereum Client](../Libraries/Seth)
179+
- [Framework Examples Directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/framework/examples/myproject)

‎Examples/Use-Cases.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Real-World Use Cases
2+
3+
This page highlights real-world scenarios where the Chainlink Testing Framework (CTF) is used to ensure reliability, performance, and security in production systems.
4+
5+
---
6+
7+
## 1. Production-Grade End-to-End Testing
8+
9+
**Scenario:**
10+
- A Chainlink-integrated DeFi protocol needs to verify that price feeds, job fulfillment, and contract upgrades work as expected across multiple networks.
11+
12+
**How CTF Helps:**
13+
- Deploys ephemeral or persistent test environments that mirror production.
14+
- Runs full workflows: contract deployment, job registration, data requests, and fulfillment.
15+
- Validates on-chain and off-chain integration.
16+
17+
---
18+
19+
## 2. CI/CD Pipeline Integration
20+
21+
**Scenario:**
22+
- Every pull request must pass a suite of integration, performance, and chaos tests before merging.
23+
24+
**How CTF Helps:**
25+
- Runs in GitHub Actions or other CI systems.
26+
- Uses caching to speed up repeated test runs.
27+
- Fails fast on regressions, configuration errors, or performance degradations.
28+
- Exposes logs and metrics for debugging failed builds.
29+
30+
---
31+
32+
## 3. Protocol Upgrade and Migration Testing
33+
34+
**Scenario:**
35+
- A new Chainlink node version or smart contract upgrade must be validated for backward compatibility and data integrity.
36+
37+
**How CTF Helps:**
38+
- Spins up old and new versions side-by-side.
39+
- Runs upgrade and migration scripts.
40+
- Verifies that jobs, data, and state persist across upgrades.
41+
- Detects breaking changes before they reach production.
42+
43+
---
44+
45+
## 4. Cross-Chain and Multi-Network Testing
46+
47+
**Scenario:**
48+
- A dApp or oracle service operates across Ethereum, Solana, and other chains, requiring cross-chain data flow validation.
49+
50+
**How CTF Helps:**
51+
- Deploys multiple blockchains in parallel.
52+
- Simulates cross-chain requests and data propagation.
53+
- Validates data consistency and latency across networks.
54+
55+
---
56+
57+
## 5. Oracle Network Resilience and Chaos Engineering
58+
59+
**Scenario:**
60+
- The reliability of a Chainlink DON (Decentralized Oracle Network) must be tested under network partitions, node failures, and resource exhaustion.
61+
62+
**How CTF Helps:**
63+
- Uses Havoc to inject network latency, pod failures, and resource limits.
64+
- Monitors system health and recovery.
65+
- Validates that the DON continues to serve data or recovers gracefully.
66+
67+
---
68+
69+
## 6. Performance Benchmarking and Load Testing
70+
71+
**Scenario:**
72+
- A new Chainlink job type or protocol feature must be benchmarked for throughput and latency under load.
73+
74+
**How CTF Helps:**
75+
- Uses WASP to generate synthetic or user-based load.
76+
- Collects metrics via Prometheus and visualizes in Grafana.
77+
- Identifies bottlenecks and regression points.
78+
79+
---
80+
81+
## 7. Staging Environment Validation
82+
83+
**Scenario:**
84+
- Before a mainnet release, the team wants to validate the full stack in a persistent staging environment.
85+
86+
**How CTF Helps:**
87+
- Reuses cached components and substitutes staging URLs.
88+
- Runs upgrade, chaos, and performance tests against the staging stack.
89+
- Ensures production readiness with minimal manual intervention.
90+
91+
---
92+
93+
## 8. Custom Component and Plugin Testing
94+
95+
**Scenario:**
96+
- A team develops a custom Chainlink external adapter or plugin and needs to validate it in a realistic environment.
97+
98+
**How CTF Helps:**
99+
- Easily adds custom components to the test config.
100+
- Runs integration and chaos tests with the new plugin.
101+
- Validates compatibility with existing Chainlink nodes and contracts.
102+
103+
---
104+
105+
## More Use Cases
106+
- [Chainlink Blog: Testing at Scale](https://blog.chain.link/)
107+
- [Framework Examples Directory](https://github.com/smartcontractkit/chainlink-testing-framework/tree/main/framework/examples/myproject)

0 commit comments

Comments
 (0)