Skip to main content
Headless mode allows you to run Chainbench tests without a web UI, making it ideal for automated testing, CI/CD pipelines, and remote server deployments.

​
Basic Headless Test

Add the --headless flag to run without the web interface: 
chainbench start --profile bsc.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless
This runs a load test for BSC with:
  • 4 worker processes
  • 100 simulated users
  • 1 hour duration
  • No web UI
In headless mode, you must specify --users, --test-time, and other parameters via command-line flags. The web interface for adjusting these values will not be available.

​
Automatic Termination with Autoquit

The --autoquit flag tells Chainbench to automatically exit after the test completes: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit
Always use --autoquit with --headless for automated testing environments. This ensures the process terminates cleanly after the test finishes.

​
Running Tests on Remote Servers

When running tests on remote servers, use nohup to prevent the process from terminating when you disconnect: 
nohup chainbench start --profile bsc.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit &
This command:
  • Runs the process in the background (&)
  • Prevents termination on disconnect (nohup)
  • Automatically quits when the test completes (--autoquit)
  • Saves output to nohup.out by default
1

SSH into your remote server

Connect to the server where you want to run the test
2

Start the test with nohup

nohup chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 12h --target https://node-url --headless --autoquit &
3

Disconnect safely

You can now disconnect from the server. The test will continue running.
4

Monitor progress

Check the output file:
tail -f nohup.out

​
Custom Output Location

Redirect output to a specific file: 
nohup chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 12h --target https://node-url --headless --autoquit > test_output.log 2>&1 &

​
Testing Single Methods in Headless Mode

Test individual RPC methods without a profile: 
chainbench start eth_blockNumber --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit
This is useful for:
  • Focused performance testing of specific endpoints
  • Debugging issues with particular methods
  • Baseline measurements for comparison

​
Headless Mode with Monitors

Monitors collect additional metrics during tests and only work in headless mode: 
chainbench start --profile evm.light --users 50 --workers 2 --test-time 12h --target https://node-url --headless --autoquit -m sync-lag-monitor
The sync-lag-monitor tracks how far behind the node is by:
  • Collecting the latest block information
  • Comparing block timestamps to current time
  • Calculating sync lag metrics
Monitors are separate processes that run alongside the test. Currently, the available monitor is:
  • sync-lag-monitor: Tracks node synchronization lag

​
Results Storage

By default, results are saved to ./results/{profile_name}/{YYYY-mm-dd_HH-MM-SS}/: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit --results-dir /custom/path/results
Results include:
  • CSV files with detailed request statistics
  • HTML reports with charts and graphs
  • Exception logs
  • Summary statistics

​
Setting a Custom Run ID

Organize test runs with custom identifiers: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit --run-id experiment-001

​
Headless Mode Best Practices

Always test against test/dev nodes first before running against production infrastructure.

​
For Development Testing

chainbench start --profile evm.light --users 5 --workers 1 --test-time 30s --target https://test-node --headless --autoquit
  • Start with minimal load (few users, 1 worker)
  • Use short test durations (30s-5m)
  • Test against development nodes

​
For Production Benchmarking

chainbench start --profile ethereum.general --users 100 --workers 4 --test-time 12h --target https://node-url --headless --autoquit --size M
  • Gradually increase load over multiple test runs
  • Use appropriate test data sizes
  • Monitor node health during the test
  • Run during low-traffic periods when possible

​
Notifications

Get notified when your test completes: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 12h --target https://node-url --headless --autoquit --notify my-test-topic
This sends notifications to https://ntfy.sh/{topic} when the test starts and finishes.
Subscribe to your ntfy.sh topic on your phone or desktop to receive push notifications when long-running tests complete.

​
Troubleshooting

​
Test Not Starting

Ensure you’ve provided all required parameters:
  • --target: Node URL
  • --users: Number of users
  • --test-time: Test duration

​
Process Running After Test Completes

Make sure you’re using the --autoquit flag: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit

​
Can’t Find Results

Check the console output for the results path, or specify a custom location: 
chainbench start --profile ethereum.general --workers 4 --users 100 --test-time 1h --target https://node-url --headless --autoquit --results-dir ./my-results

Build docs developers (and LLMs) love

Get started for freeTalk to us