feat: add post_test_sleep_duration config option (#162)

## Summary
- Add `post_test_sleep_duration` config option for a configurable sleep
after each test, allowing clients time for internal cleanup between
tests
- Supports global (`runner.client.config`) and per-instance overrides,
following the existing config pattern (e.g. `wait_after_rpc_ready`)
- Wired into all three executor paths: normal, container strategy, and
checkpoint-restore

## Test plan
- [x] `go build ./pkg/config/ ./pkg/executor/` passes
- [x] `go test ./pkg/config/ ./pkg/executor/` passes
- [x] `go vet ./pkg/config/ ./pkg/executor/` passes
- [x] Manual test with a config using `post_test_sleep_duration: 200ms`
and verify sleep appears in debug logs

Author: skylenet

config.example.yaml

@@ -306,6 +306,9 @@ runner:
       # Optional: Maximum duration for the test execution phase.
       # If exceeded, the run is cancelled with "timed_out" status. Partial results are kept.
       # run_timeout: 2h
+      # Optional: Sleep duration after each test (e.g. "200ms", "1s"). Default: 0 (disabled).
+      # Useful for clients that need a brief pause between tests to let internal cleanup finish.
+      # post_test_sleep_duration: 200ms
       # Optional: Retry engine_newPayload calls when client returns SYNCING status.
       # Useful for clients with internal sync pipelines (e.g., Erigon) that may return
       # SYNCING while still processing blocks internally.
@@ -452,6 +455,7 @@ runner:
       #   wait_after_tcp_drop_connections: "10s"
       # wait_after_rpc_ready: 60s  # Instance-level override (optional)
       # run_timeout: 1h  # Instance-level override (optional)
+      # post_test_sleep_duration: 500ms  # Instance-level override (optional)
       # retry_new_payloads_syncing_state:  # Instance-level override (optional)
       #   enabled: true
       #   max_retries: 10

docs/configuration.md

@@ -525,6 +525,7 @@ runner:
 | `retry_new_payloads_syncing_state` | object | - | Retry config for SYNCING responses (see below) |
 | `resource_limits` | object | - | Container resource constraints (see [Resource Limits](#resource-limits)) |
 | `post_test_rpc_calls` | []object | - | Arbitrary RPC calls to execute after each test step (see [Post-Test RPC Calls](#post-test-rpc-calls)) |
+| `post_test_sleep_duration` | string | - | Sleep duration after each test, e.g. `200ms`, `1s` (see below) |
 | `bootstrap_fcu` | bool/object | - | Send an `engine_forkchoiceUpdatedV3` after RPC is ready to confirm the client is fully synced (see [Bootstrap FCU](#bootstrap-fcu)) |
 | `genesis` | map | - | Genesis file URLs keyed by client type |
 
@@ -704,6 +705,23 @@ The timeout covers only the test execution phase — container setup, image pull
 - When you want to enforce a maximum wall-clock time per instance
 - When running in CI/CD environments with time constraints
 
+##### Post-Test Sleep Duration
+
+The `post_test_sleep_duration` option adds a configurable pause after each test completes (after rollback and post-test RPC calls, but before the next test begins). This is useful for clients that need time to complete internal cleanup between tests.
+
+```yaml
+runner:
+  client:
+    config:
+      post_test_sleep_duration: 200ms
+```
+
+Uses Go duration format (e.g., `200ms`, `1s`, `5s`). Default is `0` (disabled).
+
+**When to use:**
+- When a client needs time for internal cleanup between tests
+- When you observe flaky results due to rapid successive test execution
+
 ##### Retry New Payloads Syncing State
 
 When `engine_newPayload` returns a `SYNCING` status, it indicates the client hasn't fully processed the parent block yet. The `retry_new_payloads_syncing_state` option configures automatic retries with exponential backoff.
@@ -875,6 +893,7 @@ runner:
 | `retry_new_payloads_syncing_state` | object | No | From `runner.client.config` | Instance-specific retry config for SYNCING responses |
 | `resource_limits` | object | No | From `runner.client.config` | Instance-specific resource limits |
 | `post_test_rpc_calls` | []object | No | From `runner.client.config` | Instance-specific post-test RPC calls (replaces global) |
+| `post_test_sleep_duration` | string | No | From `runner.client.config` | Instance-specific post-test sleep duration |
 | `bootstrap_fcu` | bool/object | No | From `runner.client.config` | Instance-specific bootstrap FCU setting |
 
 ## Resource Limits

pkg/config/config.go

@@ -596,6 +596,7 @@ type ClientDefaults struct {
 	WaitAfterRPCReady                string                            `yaml:"wait_after_rpc_ready,omitempty" mapstructure:"wait_after_rpc_ready"`
 	RunTimeout                       string                            `yaml:"run_timeout,omitempty" mapstructure:"run_timeout"`
 	PostTestRPCCalls                 []PostTestRPCCall                 `yaml:"post_test_rpc_calls,omitempty" mapstructure:"post_test_rpc_calls"`
+	PostTestSleepDuration            string                            `yaml:"post_test_sleep_duration,omitempty" mapstructure:"post_test_sleep_duration"`
 	BootstrapFCU                     *BootstrapFCUConfig               `yaml:"bootstrap_fcu,omitempty" mapstructure:"bootstrap_fcu"`
 	CheckpointRestoreStrategyOptions *CheckpointRestoreStrategyOptions `yaml:"checkpoint_restore_strategy_options,omitempty" mapstructure:"checkpoint_restore_strategy_options"`
 }
@@ -620,6 +621,7 @@ type ClientInstance struct {
 	WaitAfterRPCReady                string                            `yaml:"wait_after_rpc_ready,omitempty" mapstructure:"wait_after_rpc_ready"`
 	RunTimeout                       string                            `yaml:"run_timeout,omitempty" mapstructure:"run_timeout"`
 	PostTestRPCCalls                 []PostTestRPCCall                 `yaml:"post_test_rpc_calls,omitempty" mapstructure:"post_test_rpc_calls"`
+	PostTestSleepDuration            string                            `yaml:"post_test_sleep_duration,omitempty" mapstructure:"post_test_sleep_duration"`
 	BootstrapFCU                     *BootstrapFCUConfig               `yaml:"bootstrap_fcu,omitempty" mapstructure:"bootstrap_fcu"`
 	CheckpointRestoreStrategyOptions *CheckpointRestoreStrategyOptions `yaml:"checkpoint_restore_strategy_options,omitempty" mapstructure:"checkpoint_restore_strategy_options"`
 }
@@ -1043,6 +1045,11 @@ func (c *Config) Validate(opts ...ValidateOpts) error {
 		return err
 	}
 
+	// Validate post_test_sleep_duration settings.
+	if err := c.validatePostTestSleepDuration(); err != nil {
+		return err
+	}
+
 	// Validate run_timeout settings.
 	if err := c.validateRunTimeout(); err != nil {
 		return err
@@ -1292,6 +1299,29 @@ func (c *Config) GetWaitAfterRPCReady(instance *ClientInstance) time.Duration {
 	return d
 }
 
+// GetPostTestSleepDuration returns the duration to sleep after each test.
+// Instance-level value overrides the global default. Returns 0 if not set.
+func (c *Config) GetPostTestSleepDuration(instance *ClientInstance) time.Duration {
+	var sleepStr string
+
+	if instance.PostTestSleepDuration != "" {
+		sleepStr = instance.PostTestSleepDuration
+	} else {
+		sleepStr = c.Runner.Client.Config.PostTestSleepDuration
+	}
+
+	if sleepStr == "" {
+		return 0
+	}
+
+	d, err := time.ParseDuration(sleepStr)
+	if err != nil {
+		return 0
+	}
+
+	return d
+}
+
 // GetRunnerRunTimeout returns the global runner-level timeout that caps
 // the entire run (all instances, setup, and teardown). Returns 0 if not set.
 func (c *Config) GetRunnerRunTimeout() time.Duration {
@@ -1689,6 +1719,25 @@ func (c *Config) validateWaitAfterRPCReady() error {
 	return nil
 }
 
+// validatePostTestSleepDuration validates post_test_sleep_duration settings.
+func (c *Config) validatePostTestSleepDuration() error {
+	for _, instance := range c.Runner.Instances {
+		sleepStr := instance.PostTestSleepDuration
+		if sleepStr == "" {
+			sleepStr = c.Runner.Client.Config.PostTestSleepDuration
+		}
+
+		if sleepStr != "" {
+			if _, err := time.ParseDuration(sleepStr); err != nil {
+				return fmt.Errorf("instance %q: invalid post_test_sleep_duration %q: %w",
+					instance.ID, sleepStr, err)
+			}
+		}
+	}
+
+	return nil
+}
+
 // validateRunTimeout validates run_timeout settings.
 func (c *Config) validateRunTimeout() error {
 	if c.Runner.RunTimeout != "" {

pkg/executor/executor.go

@@ -72,6 +72,7 @@ type ExecuteOptions struct {
 	BlockLogCollector             BlockLogCollector                     // Optional collector for capturing block logs from client.
 	RetryNewPayloadsSyncingConfig *config.RetryNewPayloadsSyncingConfig // Retry config for SYNCING responses.
 	PostTestRPCCalls              []config.PostTestRPCCall              // Arbitrary RPC calls to execute after the test step.
+	PostTestSleepDuration         time.Duration                         // Sleep duration after each test (0 = disabled).
 }
 
 // ExecutionResult contains the overall execution summary.
@@ -536,6 +537,11 @@ func (e *executor) ExecuteTests(ctx context.Context, opts *ExecuteOptions) (*Exe
 			}
 		}
 
+		if opts.PostTestSleepDuration > 0 {
+			log.WithField("duration", opts.PostTestSleepDuration).Debug("Sleeping after test")
+			time.Sleep(opts.PostTestSleepDuration)
+		}
+
 		if testPassed {
 			testsPassed++
 			log.Info("Test completed successfully")

pkg/runner/lifecycle.go

@@ -587,6 +587,14 @@ func (r *runner) runContainerLifecycle(
 				}
 				return nil
 			}(),
+			PostTestSleepDuration: func() string {
+				if r.cfg.FullConfig != nil {
+					if d := r.cfg.FullConfig.GetPostTestSleepDuration(instance); d > 0 {
+						return d.String()
+					}
+				}
+				return ""
+			}(),
 			BootstrapFCU: func() *config.BootstrapFCUConfig {
 				if r.cfg.FullConfig != nil {
 					return r.cfg.FullConfig.GetBootstrapFCU(instance)
@@ -1038,6 +1046,7 @@ func (r *runner) runContainerLifecycle(
 				BlockLogCollector:             params.BlockLogCollector,
 				RetryNewPayloadsSyncingConfig: r.cfg.FullConfig.GetRetryNewPayloadsSyncingState(instance),
 				PostTestRPCCalls:              r.cfg.FullConfig.GetPostTestRPCCalls(instance),
+				PostTestSleepDuration:         r.cfg.FullConfig.GetPostTestSleepDuration(instance),
 			}
 
 			result, execErr = r.executor.ExecuteTests(execCtx, execOpts)

pkg/runner/runner.go

@@ -170,6 +170,7 @@ type ResolvedInstance struct {
 	RetryNewPayloadsSyncingState     *config.RetryNewPayloadsSyncingConfig    `json:"retry_new_payloads_syncing_state,omitempty"`
 	ResourceLimits                   *ResolvedResourceLimits                  `json:"resource_limits,omitempty"`
 	PostTestRPCCalls                 []config.PostTestRPCCall                 `json:"post_test_rpc_calls,omitempty"`
+	PostTestSleepDuration            string                                   `json:"post_test_sleep_duration,omitempty"`
 	BootstrapFCU                     *config.BootstrapFCUConfig               `json:"bootstrap_fcu,omitempty"`
 	CheckpointRestoreStrategyOptions *config.CheckpointRestoreStrategyOptions `json:"checkpoint_restore_strategy_options,omitempty"`
 }

pkg/runner/strategy_checkpoint.go

@@ -510,6 +510,7 @@ func (r *runner) runTestsWithCheckpointRestore(
 			BlockLogCollector:             params.BlockLogCollector,
 			RetryNewPayloadsSyncingConfig: r.cfg.FullConfig.GetRetryNewPayloadsSyncingState(params.Instance),
 			PostTestRPCCalls:              r.cfg.FullConfig.GetPostTestRPCCalls(params.Instance),
+			PostTestSleepDuration:         r.cfg.FullConfig.GetPostTestSleepDuration(params.Instance),
 		}
 
 		result, execErr := r.executor.ExecuteTests(ctx, execOpts)

pkg/runner/strategy_container.go

@@ -738,6 +738,7 @@ func (r *runner) runTestsWithContainerStrategy(
 			BlockLogCollector:             params.BlockLogCollector,
 			RetryNewPayloadsSyncingConfig: r.cfg.FullConfig.GetRetryNewPayloadsSyncingState(params.Instance),
 			PostTestRPCCalls:              r.cfg.FullConfig.GetPostTestRPCCalls(params.Instance),
+			PostTestSleepDuration:         r.cfg.FullConfig.GetPostTestSleepDuration(params.Instance),
 		}
 
 		result, err := r.executor.ExecuteTests(ctx, execOpts)