evm_transition_tool: Fix besu debug dump

docs/getting_started/executing_tests_command_line.md

@@ -88,6 +88,50 @@ fill tests/shanghai/eip3651_warm_coinbase/test_warm_coinbase.py::test_warm_coinb
 
     See: [Executing Tests for Features under Development](./executing_tests_dev_fork.md).
 
+## Debugging the `t8n` Command
+
+The `--t8n-dump-dir` flag can be used to dump the inputs and outputs of every call made to the `t8n` command for debugging purposes:
+
+```console
+fill --t8n-dump-dir=/tmp/evm-t8n-dump
+```
+
+For example, running:
+
+```console
+fill tests/berlin/eip2930_access_list/ --fork Berlin \
+    --t8n-dump-dir=/tmp/evm-t8n-dump
+```
+
+will produce the directory structure:
+
+```console
+/tmp/evm-t8n-dump/
+└── test_access_list_fork_Berlin
+    ├── 0
+    │   ├── alloc
+    │   ├── args
+    │   ├── env
+    │   ├── output_alloc
+    │   ├── output_result
+    │   ├── returncode
+    │   ├── stderr
+    │   ├── stdout
+    │   └── txs
+    └── 1
+        ├── alloc
+        ├── args
+        ├── env
+        ├── output_alloc
+        ├── output_result
+        ├── returncode
+        ├── stderr
+        ├── stdout
+        └── txs
+```
+
+where the directories `0` and `1` correspond to the different calls made to the `t8n` tool executed during the test. Each directory then contain files containing information corresponding to the call, for example, the `args` file contains the arguments passed to the `t8n` command and the `output_alloc` file contains the output of the `t8n` command's `--output-alloc` flag. Note, the first call is used to calculate the state root of the starting alloc and therefore has an empty transaction list.
+
 ## Other Useful Pytest Command-Line Options
 
 ```console
@@ -134,6 +178,10 @@ Arguments defining filler location and output:
                         folder structure.
   --disable-hive        Output tests skipping hive-related properties.
 
+Arguments defining debug behavior:
+  --t8n-dump-dir T8N_DUMP_DIR
+                        Path to dump the transition tool debug output.
+
 Specify the fork range to generate fixtures for:
   --forks               Display forks supported by the test framework and exit.
   --fork FORK           Only fill tests for the specified fork.

src/evm_transition_tool/besu.py

@@ -12,7 +12,7 @@
 
 from ethereum_test_forks import Fork
 
-from .transition_tool import TransitionTool
+from .transition_tool import TransitionTool, dump_files_to_directory
 
 
 class BesuTransitionTool(TransitionTool):
@@ -99,25 +99,45 @@ def evaluate(
         if self.trace:
             raise Exception("Besu `t8n-server` does not support tracing.")
 
+        input_json = {
+            "alloc": alloc,
+            "txs": txs,
+            "env": env,
+        }
+        state_json = {
+            "fork": fork_name,
+            "chainid": chain_id,
+            "reward": reward,
+        }
+        if debug_output_path:
+            dump_files_to_directory(
+                debug_output_path,
+                input_json
+                | {
+                    "state": state_json,
+                },
+            )
+
         response = requests.post(
             self.server_url,
             json={
-                "state": {
-                    "fork": fork_name,
-                    "chainid": chain_id,
-                    "reward": reward,
-                },
-                "input": {
-                    "alloc": alloc,
-                    "txs": txs,
-                    "env": env,
-                },
+                "state": state_json,
+                "input": input_json,
             },
             timeout=5,
         )
         response.raise_for_status()  # exception visible in pytest failure output
         output = response.json()
 
+        if debug_output_path:
+            dump_files_to_directory(
+                debug_output_path,
+                {
+                    "output_alloc": output["alloc"],
+                    "output_result": output["result"],
+                },
+            )
+
         return output["alloc"], output["result"]
 
     def version(self) -> str:

src/pytest_plugins/test_help/test_help.py

@@ -43,6 +43,7 @@ def show_test_help(config):
         "solc",
         "fork range",
         "filler location",
+        "defining debug",  # the "debug" group in test_filler plugin.
     ]
 
     test_parser = argparse.ArgumentParser()