Forknet Scenario Tool

The forknet_scenario.py script is used to run test scenarios.

Prerequisites

• GCP access (SRE)
• Infra-ops access (SRE)
• Install gcloud tools locally link
• Understand the basics of forknet from mirror

Usage

1. Go to pytest directory.
2. Create the nodes:

python tests/mocknet/forknet_scenario.py --unique-id UNIQUE-ID --test-case Example create

3. Start the test

python tests/mocknet/forknet_scenario.py --unique-id token --test-case Example start --neard-upgrade-binary-url $NEARD_UPGRADE_BINARY_URL

4. Stop the test and free the nodes

python tests/mocknet/forknet_scenario.py --unique-id token --test-case Example destroy

Adding testcase

The test case functions will be executed sequentially in the order defined in forknet_scenario.py. To add a new test scenario:

1. Create a new class in tests/mocknet/forknet_scenarios/ that inherits from TestSetup base class

2. Define required parameters in __init__:

   def __init__(self, args):
      super().__init__(args)
   
      # Required parameters:
      self.start_height = 123456789  # Forknet image height
      self.args.start_height = self.start_height
   
      self.node_hardware_config = NodeHardware.SameConfig(
         num_chunk_producer_seats=19, # Number of block producers and chunk producers
         num_chunk_validator_seats=24, # Total number of validator nodes in the network.
      )
   
      self.epoch_len = 18000  # Epoch length in blocks
      self.genesis_protocol_version = 77  # Protocol version
   
      # Optional parameters:
      self.has_archival = True  # Enable archival nodes
      self.has_state_dumper = False  # Enable state dumper
      self.regions = None  # List of GCP regions, None for default
      # Set base binary URL for initial network state
      self.neard_binary_url = 'https://...'
   

3. Override methods to customize behavior:

   • before_test_setup() - Run commands before test creation
   • amend_configs_before_test_start() - Modify node configs before start
   • after_test_start() - Run commands after test starts

4. Scenario building blocks

For more complex actions, you need to define the behaviour by scheduling actions using run-cmd in the mirror lib.

As a rule of thumb, if the run-cmd is too long, consider uploading it as a helper script. (see send-stake-proposal.sh)

Some of the functions are already defined in base.py and can be used in your after_test_start() override.

• _schedule_upgrade_nodes_every_n_minutes: for a uniform upgrade.
• _schedule_binary_upgrade: if you want more granular control over how the hosts are upgraded.
• _send_stake_proposal: if you need to stake or unstake validators.