Add modular testing utilites

---------

Co-authored-by: Alexander Keating <keating.dev@protonmail.com>

Add modular testing natspec (#150)

* Add modular testing natspec

Author: alexkeating

src/test/BinaryEligibilityOracleEarningPowerCalculatorTestBase.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+pragma solidity ^0.8.23;
+
+import {BinaryEligibilityOracleEarningPowerCalculator} from
+  "src/calculators/BinaryEligibilityOracleEarningPowerCalculator.sol";
+import {MintRewardNotifier} from "../notifiers/MintRewardNotifier.sol";
+import {StakerTestBase} from "./StakerTestBase.sol";
+import {Staker} from "../Staker.sol";
+
+/// @title BinaryEligibilityOracleEarningPowerCalculatorTestBase
+/// @author [ScopeLift](https://scopelift.co)
+/// @notice The base contract for testing BinaryEligibilityOracleEarningPowerCalculator. Contains
+/// test setup and helper functions for testing the calculator's behavior when delegatees meet
+/// the eligibility threshold. This includes stake management and eligibility threshold testing
+/// functionality.
+/// @dev This contract requires an initialized instance of
+/// `BinaryEligibilityOracleEarningPowerCalculator`. Initialization is typically handled by a
+/// deployment script such as
+/// `src/script/calculators/DeployBinaryEligibilityOracleEarningPowerCalculator.sol`.
+abstract contract BinaryEligibilityOracleEarningPowerCalculatorTestBase is StakerTestBase {
+  BinaryEligibilityOracleEarningPowerCalculator calculator;
+  MintRewardNotifier mintRewardNotifier;
+
+  /// @notice A helper function that updates the delegatee score for a given deposit to a random
+  /// value between 0 and twice the eligibility threshold, facilitating tests for both eligible and
+  /// ineligible delegatee scenarios.
+  /// @param _depositId The identifier of the deposit whose delegatee's score is to be updated.
+  function _updateEarningPower(Staker.DepositIdentifier _depositId) internal virtual override {
+    uint256 _delegateeeScore = vm.randomUint(0, calculator.delegateeEligibilityThresholdScore() * 2);
+    Staker.Deposit memory _deposit = _fetchDeposit(_depositId);
+    vm.startPrank(calculator.scoreOracle());
+    calculator.updateDelegateeScore(_deposit.delegatee, _delegateeeScore);
+    vm.stopPrank();
+  }
+
+  /// @notice Bound the mint amount to a realistic value.
+  /// @dev Override of the base contract's function to set appropriate bounds for this calculator.
+  /// @param _amount The unbounded mint amount.
+  /// @return The bounded mint amount.
+  function _boundMintAmount(uint256 _amount) internal pure virtual override returns (uint256) {
+    return bound(_amount, 1, 100_000_000e18);
+  }
+}

src/test/MintRewardNotifierTestBase.sol

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+
+pragma solidity ^0.8.23;
+
+import {MintRewardNotifier} from "../notifiers/MintRewardNotifier.sol";
+import {StakerTestBase} from "./StakerTestBase.sol";
+
+/// @title MintRewardNotifierTestBase
+/// @author [ScopeLift](https://scopelift.co)
+/// @notice Base contract for testing a staker contract with a single `MintRewardNotifier`. Extends
+/// `StakerTestBase` and implements the reward notification logic.
+/// @dev This contract requires an initialized instance of `MintRewardNotifier`. Initialization is
+/// typically handled by a deployment script such as
+/// `src/script/notifiers/DeployMintRewardNotifier.sol`
+abstract contract MintRewardNotifierTestBase is StakerTestBase {
+  MintRewardNotifier mintRewardNotifier;
+
+  /// @notice Sets the reward amount, then calls the `notify` function that triggers token minting
+  /// and reward distribution.
+  function _notifyRewardAmount(uint256 _amount) public override {
+    address _owner = mintRewardNotifier.owner();
+
+    vm.prank(_owner);
+    mintRewardNotifier.setRewardAmount(_amount);
+
+    mintRewardNotifier.notify();
+  }
+}

src/test/StakedBinaryEligibilityOracleEarningPowerCalculatorTestSuite.sol

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// slither-disable-start reentrancy-benign
+
+pragma solidity ^0.8.23;
+
+import {BinaryEligibilityOracleEarningPowerCalculator} from
+  "../calculators/BinaryEligibilityOracleEarningPowerCalculator.sol";
+import {StakerTestBase} from "./StakerTestBase.sol";
+import {Staker} from "../Staker.sol";
+import {BinaryEligibilityOracleEarningPowerCalculatorTestBase} from
+  "./BinaryEligibilityOracleEarningPowerCalculatorTestBase.sol";
+
+/// @title StakedBinaryEligibilityOracleEarningPowerCalculatorTestSuite
+/// @author [ScopeLift](https://scopelift.co)
+/// @notice The base contract for testing BinaryEligibilityOracleEarningPowerCalculator. Contains
+/// test setup and helper functions for testing the calculator's behavior when delegatees are below
+/// the eligibility threshold. This contract is designed to be used in conjunction with the
+/// deployment scripts in
+/// `src/script/calculators/DeployBinaryEligibilityOracleEarningPowerCalculator.sol`.
+abstract contract StakedBinaryEligibilityOracleEarningPowerCalculatorTestBase is
+  BinaryEligibilityOracleEarningPowerCalculatorTestBase
+{
+  /// @notice Helper to set a delegatee's score below threshold.
+  /// @param delegatee The address of the delegatee whose score will be set below threshold.
+  function _setDelegateeScoreBelowThreshold(address delegatee) internal {
+    vm.startPrank(calculator.scoreOracle());
+    calculator.updateDelegateeScore(delegatee, calculator.delegateeEligibilityThresholdScore() - 1);
+    vm.stopPrank();
+  }
+
+  /// @notice A test helper that wraps calling the `stake` function and ensures proper earning power
+  /// adjustment when delegatee scores are below threshold.
+  /// @param _depositor The address of the depositor.
+  /// @param _amount The amount to stake.
+  /// @param _delegatee The address to which the delegation surrogate is delegating voting power.
+  /// @return _depositId The id of the created deposit.
+  function _stakeBelowThreshold(address _depositor, uint256 _amount, address _delegatee)
+    internal
+    virtual
+    returns (Staker.DepositIdentifier _depositId)
+  {
+    _depositId = StakerTestBase._stake(_depositor, _amount, _delegatee);
+    _setDelegateeScoreBelowThreshold(_delegatee);
+  }
+
+  /// @notice Helper to set a delegatee's score above the eligibility threshold.
+  /// @dev This should be called after a delegatee is known but before checking their earning power.
+  /// @param delegatee The address of the delegatee whose score will be set above threshold.
+  function _setDelegateeScoreAboveThreshold(address delegatee) internal {
+    vm.startPrank(calculator.scoreOracle());
+    calculator.updateDelegateeScore(delegatee, calculator.delegateeEligibilityThresholdScore() + 1);
+    vm.stopPrank();
+  }
+
+  /// @notice A test helper that wraps calling the `stake` function and ensures proper earning power
+  /// adjustment when delegatee scores are above threshold.
+  /// @param _depositor The address of the depositor.
+  /// @param _amount The amount to stake.
+  /// @param _delegatee The address to which the delegation surrogate is delegating voting power.
+  /// @return _depositId The id of the created deposit.
+  function _stakeAboveThreshold(address _depositor, uint256 _amount, address _delegatee)
+    internal
+    virtual
+    returns (Staker.DepositIdentifier _depositId)
+  {
+    _depositId = StakerTestBase._stake(_depositor, _amount, _delegatee);
+
+    _setDelegateeScoreAboveThreshold(_delegatee);
+    vm.startPrank(_depositor);
+    staker.bumpEarningPower(_depositId, _depositor, 0);
+    vm.stopPrank();
+  }
+}
+
+abstract contract StakeBase is StakedBinaryEligibilityOracleEarningPowerCalculatorTestBase {
+  function testFuzz_StakerEarnsZeroRewardsWhenDelegateeScoreIsBelowThreshold(
+    address _depositor,
+    uint96 _amount,
+    address _delegatee,
+    uint256 _rewardAmount,
+    uint256 _percentDuration
+  ) public {
+    _assumeNotZeroAddressOrStaker(_depositor);
+    vm.assume(_delegatee != address(0) && _amount != 0);
+
+    _mintStakeToken(_depositor, _amount);
+    _rewardAmount = _boundToRealisticReward(_rewardAmount);
+    _percentDuration = bound(_percentDuration, 1, 100);
+
+    Staker.DepositIdentifier _depositId = _stakeBelowThreshold(_depositor, _amount, _delegatee);
+
+    _notifyRewardAmount(_rewardAmount);
+    _jumpAheadByPercentOfRewardDuration(_percentDuration);
+
+    uint256 unclaimedRewards = staker.unclaimedReward(_depositId);
+
+    assertEq(unclaimedRewards, 0);
+  }
+}
+
+abstract contract WithdrawBase is StakedBinaryEligibilityOracleEarningPowerCalculatorTestBase {
+  function testFuzz_OnlyStakeWithEligibleEarningPowerClaimsRewardAfterDuration(
+    address _depositor1,
+    address _depositor2,
+    uint96 _amount1,
+    uint96 _amount2,
+    address _delegatee1,
+    address _delegatee2,
+    uint256 _rewardAmount,
+    uint256 _percentDuration
+  ) public {
+    _assumeNotZeroAddressOrStaker(_depositor1);
+    _assumeNotZeroAddressOrStaker(_depositor2);
+    vm.assume(_depositor1 != _depositor2);
+    vm.assume(_delegatee1 != address(0) && _delegatee2 != address(0) && _delegatee1 != _delegatee2);
+
+    _amount1 = uint96(_boundMintAmount(_amount1));
+    _amount2 = uint96(_boundMintAmount(_amount2));
+    vm.assume(_amount1 != 0 && _amount2 != 0);
+
+    _mintStakeToken(_depositor1, _amount1);
+    _mintStakeToken(_depositor2, _amount2);
+
+    Staker.DepositIdentifier _depositId1 = _stakeBelowThreshold(_depositor1, _amount1, _delegatee1);
+    Staker.DepositIdentifier _depositId2 = _stakeAboveThreshold(_depositor2, _amount2, _delegatee2);
+
+    _rewardAmount = _boundToRealisticReward(_rewardAmount);
+    _notifyRewardAmount(_rewardAmount);
+    _percentDuration = bound(_percentDuration, 1, 100);
+    _jumpAheadByPercentOfRewardDuration(_percentDuration);
+
+    Staker.Deposit memory _deposit2 = _fetchDeposit(_depositId2);
+    uint256 _calculatedRewards2 =
+      _calculateEarnedRewards(_deposit2.earningPower, _rewardAmount, _percentDuration);
+
+    _withdraw(_depositor1, _depositId1, _amount1);
+    _withdraw(_depositor2, _depositId2, _amount2);
+
+    vm.prank(_depositor1);
+    uint256 _actualReward1 = staker.claimReward(_depositId1);
+
+    vm.prank(_depositor2);
+    uint256 _actualReward2 = staker.claimReward(_depositId2);
+
+    assertEq(0, _actualReward1);
+    assertApproxEqAbs(_calculatedRewards2, _actualReward2, 1);
+  }
+}