feat(consume): add --enginex-fcu-frequency option

Author: danceratopz

src/cli/pytest_commands/consume.py

@@ -114,10 +114,36 @@ def engine() -> None:
     pass
 
 
-@consume_command(is_hive=True)
-def enginex() -> None:
+@consume.command(
+    name="enginex",
+    help="Client consumes Engine X Fixtures via the Engine API.",
+    context_settings={"ignore_unknown_options": True},
+)
+@click.option(
+    "--enginex-fcu-frequency",
+    type=int,
+    default=1,
+    help=(
+        "Control forkchoice update frequency for enginex simulator. "
+        "0=disable FCUs, 1=FCU every test (default), N=FCU every Nth test per "
+        "pre-allocation group."
+    ),
+)
+@common_pytest_options
+def enginex(enginex_fcu_frequency: int, pytest_args: List[str], **_kwargs) -> None:
     """Client consumes Engine X Fixtures via the Engine API."""
-    pass
+    command_name = "enginex"
+    command_paths = get_command_paths(command_name, is_hive=True)
+
+    # Validate the frequency parameter
+    if enginex_fcu_frequency < 0:
+        raise click.BadParameter("FCU frequency must be non-negative")
+
+    # Add the FCU frequency to pytest args as a custom config option
+    pytest_args_with_fcu = [f"--enginex-fcu-frequency={enginex_fcu_frequency}"] + list(pytest_args)
+
+    consume_cmd = ConsumeCommand(command_paths, is_hive=True, command_name=command_name)
+    consume_cmd.execute(pytest_args_with_fcu)
 
 
 @consume_command(is_hive=True)

src/pytest_plugins/consume/simulators/enginex/conftest.py

@@ -25,10 +25,29 @@
 )
 
 
+def pytest_addoption(parser):
+    """Add enginex-specific command line options."""
+    enginex_group = parser.getgroup("enginex", "EngineX simulator options")
+    enginex_group.addoption(
+        "--enginex-fcu-frequency",
+        action="store",
+        type=int,
+        default=1,
+        help=(
+            "Control forkchoice update frequency for enginex simulator. "
+            "0=disable FCUs, 1=FCU every test (default), N=FCU every Nth test per "
+            "pre-allocation group."
+        ),
+    )
+
+
 def pytest_configure(config):
-    """Set the supported fixture formats for the engine simulator."""
+    """Set the supported fixture formats and store enginex configuration."""
     config._supported_fixture_formats = [BlockchainEngineXFixture.format_name]
 
+    # Store FCU frequency on config for access by fixtures
+    config.enginex_fcu_frequency = config.getoption("--enginex-fcu-frequency", 1)
+
 
 @pytest.fixture(scope="module")
 def test_suite_name() -> str:
@@ -104,3 +123,23 @@ def engine_rpc(client: Client, client_exception_mapper: ExceptionMapper | None)
             },
         )
     return EngineRPC(f"http://{client.ip}:8551")
+
+
+@pytest.fixture(scope="session")
+def fcu_frequency_tracker(request):
+    """
+    Session-scoped FCU frequency tracker for enginex simulator.
+
+    This fixture is imported from test_tracker module and configured
+    with the --enginex-fcu-frequency command line option.
+    """
+    # Import here to avoid circular imports
+    from ..helpers.test_tracker import FCUFrequencyTracker
+
+    # Get FCU frequency from pytest config (set by command line argument)
+    fcu_frequency = getattr(request.config, "enginex_fcu_frequency", 1)
+
+    tracker = FCUFrequencyTracker(fcu_frequency=fcu_frequency)
+    logger.info(f"FCU frequency tracker initialized with frequency: {fcu_frequency}")
+
+    return tracker

src/pytest_plugins/consume/simulators/helpers/test_tracker.py

@@ -175,3 +175,102 @@ def pre_alloc_group_test_tracker(request) -> PreAllocGroupTestTracker:
 
     logger.info("Pre-allocation group test tracker initialized")
     return tracker
+
+
+@dataclass
+class FCUFrequencyTracker:
+    """
+    Tracks forkchoice update frequency per pre-allocation group.
+
+    This class enables controlling how often forkchoice updates are performed
+    during test execution on a per-pre-allocation-group basis.
+    """
+
+    fcu_frequency: int
+    """Frequency of FCU operations (0=disabled, 1=every test, N=every Nth test)."""
+
+    group_test_counters: Dict[str, int] = field(default_factory=dict)
+    """Test counters per pre-allocation group (pre_hash -> count)."""
+
+    def should_perform_fcu(self, pre_hash: str) -> bool:
+        """
+        Check if forkchoice update should be performed for this test.
+
+        Args:
+            pre_hash: The pre-allocation group hash
+
+        Returns:
+            True if FCU should be performed for this test
+
+        """
+        if self.fcu_frequency == 0:
+            logger.debug(f"FCU disabled for pre-allocation group {pre_hash} (frequency=0)")
+            return False
+
+        current_count = self.group_test_counters.get(pre_hash, 0)
+        should_perform = (current_count % self.fcu_frequency) == 0
+
+        logger.debug(
+            f"FCU decision for pre-allocation group {pre_hash}: "
+            f"perform={should_perform} (test_count={current_count}, "
+            f"frequency={self.fcu_frequency})"
+        )
+
+        return should_perform
+
+    def increment_test_count(self, pre_hash: str) -> None:
+        """
+        Increment test counter for pre-allocation group.
+
+        Args:
+            pre_hash: The pre-allocation group hash
+
+        """
+        current_count = self.group_test_counters.get(pre_hash, 0)
+        new_count = current_count + 1
+        self.group_test_counters[pre_hash] = new_count
+
+        logger.debug(
+            f"Incremented test count for pre-allocation group {pre_hash}: "
+            f"{current_count} -> {new_count}"
+        )
+
+    def get_test_count(self, pre_hash: str) -> int:
+        """
+        Get current test count for pre-allocation group.
+
+        Args:
+            pre_hash: The pre-allocation group hash
+
+        Returns:
+            Current test count for the group
+
+        """
+        return self.group_test_counters.get(pre_hash, 0)
+
+    def get_all_test_counts(self) -> Dict[str, int]:
+        """
+        Get test counts for all tracked pre-allocation groups.
+
+        Returns:
+            Dict mapping pre_hash to test count
+
+        """
+        return dict(self.group_test_counters)
+
+    def reset_group(self, pre_hash: str) -> None:
+        """
+        Reset test counter for a specific pre-allocation group.
+
+        Args:
+            pre_hash: The pre-allocation group hash to reset
+
+        """
+        if pre_hash in self.group_test_counters:
+            del self.group_test_counters[pre_hash]
+        logger.debug(f"Reset test counter for pre-allocation group {pre_hash}")
+
+    def reset_all(self) -> None:
+        """Reset all test counters."""
+        self.group_test_counters.clear()
+        logger.debug("Reset all FCU frequency test counters")

src/pytest_plugins/consume/simulators/hive_tests/test_via_engine.py

@@ -34,13 +34,35 @@ def test_blockchain_via_engine(
     fixture: BlockchainEngineFixture | BlockchainEngineXFixture,
     genesis_header: FixtureHeader,
     strict_exception_matching: bool,
+    fcu_frequency_tracker=None,  # Optional for enginex simulator
+    request=None,  # For accessing test info
 ):
     """
     1. Check the client genesis block hash matches `genesis.block_hash`.
     2. Execute the test case fixture blocks against the client under test using the
     `engine_newPayloadVX` method from the Engine API.
-    3. For valid payloads a forkchoice update is performed to finalize the chain.
+    3. For valid payloads a forkchoice update is performed to finalize the chain
+       (controlled by FCU frequency for enginex simulator).
     """
+    # Determine if we should perform forkchoice updates based on frequency tracker
+    should_perform_fcus = True  # Default behavior for engine simulator
+    pre_hash = None
+
+    if fcu_frequency_tracker is not None and hasattr(fixture, "pre_hash"):
+        # EngineX simulator with forkchoice update frequency control
+        pre_hash = fixture.pre_hash
+        should_perform_fcus = fcu_frequency_tracker.should_perform_fcu(pre_hash)
+
+        logger.info(
+            f"Forkchoice update frequency check for pre-allocation group {pre_hash}: "
+            f"perform_fcu={should_perform_fcus} "
+            f"(frequency={fcu_frequency_tracker.fcu_frequency}, "
+            f"test_count={fcu_frequency_tracker.get_test_count(pre_hash)})"
+        )
+
+    # Always increment the test counter at the start for proper tracking
+    if fcu_frequency_tracker is not None and pre_hash is not None:
+        fcu_frequency_tracker.increment_test_count(pre_hash)
     # Send a initial forkchoice update
     with timing_data.time("Initial forkchoice update"):
         logger.info("Sending initial forkchoice update to genesis block...")
@@ -138,7 +160,7 @@ def test_blockchain_via_engine(
                                 f"Unexpected error code: {e.code}, expected: {payload.error_code}"
                             ) from e
 
-                if payload.valid():
+                if payload.valid() and should_perform_fcus:
                     with payload_timing.time(
                         f"engine_forkchoiceUpdatedV{payload.forkchoice_updated_version}"
                     ):
@@ -159,4 +181,18 @@ def test_blockchain_via_engine(
                                 f"unexpected status: want {PayloadStatusEnum.VALID},"
                                 f" got {forkchoice_response.payload_status.status}"
                             )
+                elif payload.valid() and not should_perform_fcus:
+                    logger.info(
+                        f"Skipping forkchoice update for payload {i + 1} due to frequency setting "
+                        f"(pre-allocation group: {pre_hash})"
+                    )
         logger.info("All payloads processed successfully.")
+
+    # Log final FCU frequency statistics for enginex simulator
+    if fcu_frequency_tracker is not None and pre_hash is not None:
+        final_count = fcu_frequency_tracker.get_test_count(pre_hash)
+        logger.info(
+            f"Test completed for pre-allocation group {pre_hash}. "
+            f"Total tests in group: {final_count}, "
+            f"FCU frequency: {fcu_frequency_tracker.fcu_frequency}"
+        )