✨ feat(fill): watch mode (#2173)

Co-authored-by: raxhvl <[email protected]>

Author: raxhvl

docs/CHANGELOG.md

@@ -14,9 +14,10 @@ Test fixtures for use by clients are available for each release on the [Github r
 
 #### `fill`
 
-- Move pytest marker registration for `fill` and `execute-*` from their respective ini files to the shared `pytest_plugins.shared.execute_fill` pytest plugin ([#2110](https://github.com/ethereum/execution-spec-tests/pull/2110)).
 - ✨ Added `--optimize-gas`, `--optimize-gas-output` and `--optimize-gas-post-processing` flags that allow to binary search the minimum gas limit value for a transaction in a test that still yields the same test result ([#1979](https://github.com/ethereum/execution-spec-tests/pull/1979)).
-- Upgraded ckzg version to 2.1.3 or newer for correct handling of points at infinity ([#2171](https://github.com/ethereum/execution-spec-tests/pull/2171)).
+- ✨ Added `--watch` flag that monitors test files for changes and automatically re-runs the fill command when developing tests ([#2173](https://github.com/ethereum/execution-spec-tests/pull/2173)).
+- 🔀 Upgraded ckzg version to 2.1.3 or newer for correct handling of points at infinity ([#2171](https://github.com/ethereum/execution-spec-tests/pull/2171)).
+- 🔀 Move pytest marker registration for `fill` and `execute-*` from their respective ini files to the shared `pytest_plugins.shared.execute_fill` pytest plugin ([#2110](https://github.com/ethereum/execution-spec-tests/pull/2110)).
 
 #### `consume`
 

docs/filling_tests/filling_tests_command_line.md

@@ -123,6 +123,52 @@ This flag automatically performs a two-phase execution:
 
 The `--evm-dump-dir` flag can be used to dump the inputs and outputs of every call made to the `t8n` command for debugging purposes, see [Debugging Transition Tools](./debugging_t8n_tools.md).
 
+## Watch Mode for Development
+
+!!! tip "Development workflow"
+    Use `--watch` or `--watcherfall` during test development to get immediate feedback on your changes without manually re-running the fill command.
+
+### Standard Watch Mode (`--watch`)
+
+This will:
+
+1. Run the initial fill command.
+2. Monitor all Python files in the `tests/` and `src/` directories for changes.
+3. Automatically re-run the fill command when changes are detected.
+4. Clear the screen and show which files changed.
+
+```console
+uv run fill tests/amsterdam/eip7928_block_level_access_lists/test_block_access_lists.py --clean --until Amsterdam --watch
+✓ Fill completed
+
+Watching for changes...
+
+```
+
+### Watcherfall Watch Mode (`--watcherfall`)
+
+!!! info "Watcherfall mode"
+    A verbose mode; like watch but the logs keep flowing - perfect when you want to see the full history of runs without clearing the terminal.
+
+Same as `--watch` but without clearing the terminal between runs, so you can see the full output history:
+
+```console
+uv run fill tests/amsterdam/eip7928_block_level_access_lists/test_block_access_lists.py --clean --until Amsterdam --watcherfall
+Starting watcherfall mode (verbose)...
+✓ Fill completed
+
+Watching for changes...
+
+File changes detected, re-running...
+
+✓ Fill completed
+
+Watching for changes...
+
+```
+
+Exit either watch mode with Ctrl+C
+
 ## Other Useful Pytest Command-Line Options
 
 ```console

src/cli/pytest_commands/fill.py

@@ -5,7 +5,8 @@
 import click
 
 from .base import PytestCommand, PytestExecution, common_pytest_options
-from .processors import HelpFlagsProcessor, StdoutFlagsProcessor
+from .processors import HelpFlagsProcessor, StdoutFlagsProcessor, WatchFlagsProcessor
+from .watcher import FileWatcher
 
 
 class FillCommand(PytestCommand):
@@ -18,6 +19,7 @@ def __init__(self, **kwargs):
             argument_processors=[
                 HelpFlagsProcessor("fill"),
                 StdoutFlagsProcessor(),
+                WatchFlagsProcessor(),
             ],
             **kwargs,
         )
@@ -174,6 +176,27 @@ def _is_tarball_output(self, args: List[str]) -> bool:
                 return str(output_path).endswith(".tar.gz")
         return False
 
+    def _is_watch_mode(self, args: List[str]) -> bool:
+        """Check if any watch flag is present in arguments."""
+        return any(flag in args for flag in ["--watch", "--watcherfall"])
+
+    def _is_verbose_watch_mode(self, args: List[str]) -> bool:
+        """Check if verbose watch flag (--watcherfall) is present in arguments."""
+        return "--watcherfall" in args
+
+    def execute(self, pytest_args: List[str]) -> None:
+        """Execute the command with optional watch mode support."""
+        if self._is_watch_mode(pytest_args):
+            self._execute_with_watch(pytest_args)
+        else:
+            super().execute(pytest_args)
+
+    def _execute_with_watch(self, pytest_args: List[str]) -> None:
+        """Execute fill command in watch mode."""
+        verbose = self._is_verbose_watch_mode(pytest_args)
+        watcher = FileWatcher(console=self.runner.console, verbose=verbose)
+        watcher.run_with_watch(pytest_args)
+
 
 class PhilCommand(FillCommand):
     """Friendly fill command with emoji reporting."""

src/cli/pytest_commands/processors.py

@@ -118,6 +118,14 @@ def _has_parallelism_flag(self, args: List[str]) -> bool:
         return "-n" in args
 
 
+class WatchFlagsProcessor(ArgumentProcessor):
+    """Processes --watch and --watcherfall flags for file watching functionality."""
+
+    def process_args(self, args: List[str]) -> List[str]:
+        """Remove --watch and --watcherfall flags from args passed to pytest."""
+        return [arg for arg in args if arg not in ["--watch", "--watcherfall"]]
+
+
 class ConsumeCommandProcessor(ArgumentProcessor):
     """Processes consume-specific command arguments."""
 

src/cli/pytest_commands/watcher.py

@@ -0,0 +1,86 @@
+"""File watcher implementation for --watch flag functionality."""
+
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Dict
+
+from rich.console import Console
+
+
+class FileWatcher:
+    """Simple file watcher that re-runs the fill command on changes."""
+
+    def __init__(self, console=None, verbose=False):
+        """Initialize the file watcher."""
+        self.console = console or Console(highlight=False)
+        self.verbose = verbose
+
+    def run_with_watch(self, args):
+        """Watch for file changes and re-run fill command."""
+        file_mtimes: Dict[Path, float] = {}
+
+        def get_file_mtimes():
+            """Get current modification times of all test and source files."""
+            mtimes = {}
+            # Watch tests directory
+            tests_dir = Path("tests")
+            if tests_dir.exists():
+                for py_file in tests_dir.rglob("*.py"):
+                    try:
+                        mtimes[py_file] = py_file.stat().st_mtime
+                    except (OSError, FileNotFoundError):
+                        pass
+            # Watch src directory
+            src_dir = Path("src")
+            if src_dir.exists():
+                for py_file in src_dir.rglob("*.py"):
+                    try:
+                        mtimes[py_file] = py_file.stat().st_mtime
+                    except (OSError, FileNotFoundError):
+                        pass
+            return mtimes
+
+        def run_fill():
+            """Run fill command without --watch / --watcherfall flag."""
+            clean_args = [arg for arg in args if arg not in ["--watch", "--watcherfall"]]
+            cmd = ["uv", "run", "fill"] + clean_args
+            result = subprocess.run(cmd)
+
+            if result.returncode == 0:
+                self.console.print("[green]✓ Fill completed[/green]")
+            else:
+                self.console.print(f"[red]✗ Fill failed (exit {result.returncode})[/red]")
+
+        # Setup
+        mode_desc = "watcherfall mode (verbose)" if self.verbose else "watch mode"
+        self.console.print(f"[blue]Starting {mode_desc}...[/blue]")
+        file_mtimes = get_file_mtimes()
+
+        # Initial run
+        self.console.print("[green]Running initial fill...[/green]")
+        run_fill()
+
+        file_count = len(file_mtimes)
+        self.console.print(
+            f"[blue]Watching {file_count} files in tests/ and src/ directories."
+            "\n Press Ctrl+C to stop.[/blue]"
+        )
+
+        # Watch loop
+        try:
+            while True:
+                time.sleep(0.5)
+                current_mtimes = get_file_mtimes()
+
+                if current_mtimes != file_mtimes:
+                    if not self.verbose:
+                        os.system("clear" if os.name != "nt" else "cls")
+                    self.console.print("[yellow]File changes detected, re-running...[/yellow]\n")
+                    run_fill()
+                    file_mtimes = current_mtimes
+                    self.console.print("\n[blue]Watching for changes...[/blue]")
+
+        except KeyboardInterrupt:
+            self.console.print("\n[yellow]Watch mode stopped.[/yellow]")

whitelist.txt

@@ -1071,4 +1071,5 @@ CLZ
 Fujisan
 zkevm
 jsign
-Glamsterdam
+Glamsterdam
+Watcherfall