Improve the random port function docs

[teor2345]

Motivation

It's hard to know when to use the random port function in the acceptance tests.

Solution

Improve the random port function docs

Also:

• rename the function
• create an alternative function for the common case.

The code in this pull request has:

• Documentation Comments

Review

@oxarbitrage is about to use this code, this PR should merge before the new acceptance tests that use these functions.

Related Issues

Blocks tests for #1535

[oxarbitrage]

The PR looks good, there is a test failure in the CI, seems unrelated but maybe we should double check before merge.

[teor2345]

The PR looks good, there is a test failure in the CI, seems unrelated but maybe we should double check before merge.

I don't see any test failures in the list of 14 checks in the GitHub PR. But I can see that the Windows large sync test is still running. That's not surprising, because testnet can be slow, and we're still working on fixing the hangs in #1435

[oxarbitrage]

There was an error in macos. did you restarted ?

I still have the tab open with it:

Exit Status:
   command terminated unsuccessfully by signal 9

Match Regex:
   "stopping at configured height"

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                ⋮ 10 frames hidden ⋮                              
  11: zebra_test::command::TestChild<T>::expect_stdout::h3e549148b29cce84
      at /Users/runner/work/zebra/zebra/zebra-test/src/command.rs:254
       252 │         }
       253 │ 
       254 >         let report = eyre!("stdout of command did not contain any matches for the given regex")
       255 │             .context_from(self)
       256 │             .with_section(|| format!("{:?}", regex).header("Match Regex:"));
  12: acceptance::sync_until::hd75ff2010313b6dd
      at /Users/runner/work/zebra/zebra/zebrad/tests/acceptance.rs:652
       650 │     // TODO: is there a way to check for testnet or mainnet here?
       651 │     // For example: "network=Mainnet" or "network=Testnet"
       652 >     child.expect_stdout(stop_regex)?;
       653 │     child.kill()?;
       654 │ 
  13: acceptance::sync_one_checkpoint_mainnet::h3ac6003d12e1d926
      at /Users/runner/work/zebra/zebra/zebrad/tests/acceptance.rs:515
       513 │ #[test]
       514 │ fn sync_one_checkpoint_mainnet() -> Result<()> {
       515 >     sync_until(
       516 │         Height(0),
       517 │         Mainnet,
  14: acceptance::sync_one_checkpoint_mainnet::{{closure}}::hd67cb90aacc1e125
      at /Users/runner/work/zebra/zebra/zebrad/tests/acceptance.rs:514
       512 │ /// The first checkpoint contains a single genesis block.
       513 │ #[test]
       514 > fn sync_one_checkpoint_mainnet() -> Result<()> {
       515 │     sync_until(
       516 │         Height(0),
                                ⋮ 2 frames hidden ⋮                               
  17: test::__rust_begin_short_backtrace::h8c20647892dadc50
      at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/test/src/lib.rs:516
                                ⋮ 19 frames hidden ⋮                              

Run with COLORBT_SHOW_HIDDEN=1 environment variable to disable frame filtering.
---- end of test output ----

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BACKTRACE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
                                ⋮ 13 frames hidden ⋮                              
  14: acceptance::sync_one_checkpoint_mainnet::{{closure}}::hd67cb90aacc1e125
      at /Users/runner/work/zebra/zebra/zebrad/tests/acceptance.rs:514
       512 │ /// The first checkpoint contains a single genesis block.
       513 │ #[test]
       514 > fn sync_one_checkpoint_mainnet() -> Result<()> {
       515 │     sync_until(
       516 │         Height(0),
                                ⋮ 2 frames hidden ⋮                               
  17: test::__rust_begin_short_backtrace::h8c20647892dadc50
      at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/test/src/lib.rs:516
                                ⋮ 19 frames hidden ⋮                              

Run with COLORBT_SHOW_HIDDEN=1 environment variable to disable frame filtering.


failures:
    sync_one_checkpoint_mainnet

test result: FAILED. 17 passed; 1 failed; 2 ignored; 0 measured; 0 filtered out

error: test failed, to rerun pass '-p zebrad --test acceptance'
Error: The process '/Users/runner/.cargo/bin/cargo' failed with exit code 101

[teor2345]

I didn't restart the PR, and it's all green for me. It looks like that error is #1435.

[dconnolly]

(i restarted it 🙈)

[oxarbitrage]

Thanks @dconnolly