decred.org/dcrdex@v1.0.5/dex/testing/firo/README_HARNESS.md (about)

     1  # Firo Chain Server Test Harness
     2  
     3  The harness is a collection of tmux scripts that collectively creates a
     4  sandboxed environment for testing dex swap transactions.
     5  
     6  ## Dependencies
     7  
     8  The harness depends on [firod] and [firo-cli] to run.
     9  Go to <https://github.com/firoorg/firo/releases> for binaries or source.
    10  
    11  ## Using
    12  
    13  You must have `firod` and `firo-cli` in `PATH` to use the harness.
    14  
    15  The harness script will create four connected regtest nodes **alpha**, **beta**,
    16  **gamma**, **delta**. Each node will have one empty but encrypted wallet. The script will mine some blocks and send some regular transactions.
    17  
    18  This simnet harness sets up 4 Firo nodes and a set of harness controls
    19  Each node has a prepared, encrypted, empty wallet
    20  
    21  ```text
    22  alpha/
    23  ├── alpha.conf
    24  └── regtest
    25      ├── wallet.dat
    26  
    27  beta/
    28  ├── beta.conf
    29  └── regtest
    30      ├── wallet.dat
    31  
    32  gamma/
    33  ├── gamma.conf
    34  └── regtest
    35      ├── wallet.dat
    36  
    37  delta/
    38  ├── delta.conf
    39  └── regtest
    40      ├── wallet.dat
    41  
    42  └── harness-ctl
    43      ├── alpha
    44      ├── beta
    45      ├── connect-alpha
    46      ├── delta
    47      ├── gamma
    48      ├── mine-alpha
    49      ├── mine-beta
    50      ├── quit
    51      ├── reorg
    52      ├── start-wallet
    53      └── stop-wallet
    54  ```
    55  
    56  **alpha** is purely a mining node/wallet, and will have mostly coinbase
    57  UTXOs to spend.
    58  
    59  **beta**, **gamma**, **delta** will all connect to **alpha** as peers.
    60  
    61  ## Harness Control Scripts
    62  
    63  The `./harness.sh` script will drop you into a tmux window in a directory
    64  called `harness-ctl`. Inside this directory are a number of scripts to
    65  allow you to perform RPC calls against each wallet.
    66  
    67  `./alpha` `./beta` `./gamma` `./delta` are just `firo-cli` configured for their
    68  respective node-wallets.
    69  
    70  `./alpha getbalance`, for example.
    71  
    72  ### Other Examples 
    73  
    74  `./reorg` will step through a script that causes the alpha node to undergo a reorg.
    75  
    76  `./quit` shuts down the nodes and closes the tmux session.
    77  
    78  ## Background Miner
    79  
    80  By default the harness also sets up a background miner which mines on the alpha
    81  node every 15s. This can upset some test logic so it can be disabled by
    82  setting environment variable NOMINER="1"
    83  
    84  ## Dev Stuff
    85  
    86  If things aren't looking right, you may need to look at the node windows to
    87  see errors. In tmux, you can navigate between windows by typing `Ctrl+b` and
    88  then the window number. The window numbers are listed at the bottom
    89  of the tmux window. `Ctrl+b` followed by the number `0`, for example, will
    90  change to the alpha node window. Examining the node output to look for errors
    91  is usually a good first debugging step.
    92  
    93  An unfortunate issue that will pop up if you're fiddling with the script is
    94  zombie firod processes preventing the harness nodes from binding to the
    95  specified ports. You'll have to manually hunt down the zombie PIDs and `kill`
    96  them if this happens.
    97  
    98  ### Zombie Killer
    99  
   100  (debian)
   101  
   102  ```bash
   103  $   kill -9 <pid>                       # find & kill any running regtest daemons
   104      ...
   105  $   tmux kill-session -t firo-harness   # kill firo-harness session
   106  ```