Task/12361 help refactor v1

.env.example

@@ -0,0 +1,26 @@
+# Example configuration for pytest_start.sh.
+#
+# Copy this file to `.env` and adjust the values. All variables are
+# optional: each one provides the default for the corresponding script
+# flag, so you don't have to pass it on every run. Variables marked with
+# "# -" have no built-in default; without them (or the matching flag)
+# the script either errors out or warns.
+#
+# Mandatory (script errors out without a flag or a value here):
+DEFAULT_SURICATA_SERVER="suricata_server_name"        # -  (-s)
+DEFAULT_TREX_SERVER="trex_server_name"             # -  (-tg)
+DEFAULT_TREX_PORT1="0000:b3:00.0"       # -  (-p1)
+DEFAULT_TREX_PORT2="0000:b3:00.1"       # -  (-p2)
+DEFAULT_PCIES="0000:3b:00.0"            # -  (-p, space-separated for multiple)
+
+# Mandatory for single-port tests (warns otherwise):
+DEFAULT_TARGET_MAC="01:C2:EG:48:DE:FF"  # -  (-tm)
+
+# Optional (built-in defaults shown):
+DEFAULT_TARGET_VLAN=0                        # -  (-tv; untagged by default)
+DEFAULT_TESTS="http_simple nfs_smb_simple"   #    (-d; script default: http_simple)
+DEFAULT_TIME=300                             #    (-t)
+DEFAULT_HEATUP=0                             #    (-ht)
+DEFAULT_HUGEPAGES="6G"                       #    (-sh)
+LOGLEVEL="INFO"                              #    (-sl)
+DEFAULT_SUITE_LOG_FILE=false                 #    (-sf; set to true to enable)

.github/workflows/lint.yml

@@ -18,10 +18,10 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install dependencies
+      - name: Install ruff
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install "ruff==$(grep -oP '^ruff==\K.*' requirements.txt)"
 
       - name: Ruff check
         id: ruff_check

README.md

@@ -133,31 +133,35 @@ If you want to pass a flag to pytest directly, you can do so by adding it after
 
 ### Environment variables
 
-Optionally you can create a `.env` file with default variables, so that you don't have to fill out the flags on every run of pytests.
-The file will look like this:
+Optionally you can create a `.env` file with default values, so that you don't have to fill out the flags on every run of pytest.
+Use [`.env.example`](.env.example) as a template - it lists all supported variables together with the corresponding `pytest_start.sh` flags:
 
 ```bash
-# Variables marked with "# -" don't have any default value, otherwise
-# default values are shown
+cp .env.example .env
+```
+
+The full list of variables (each maps to a script flag shown in parentheses):
 
+```bash
 # Mandatory flags
 # if these aren't set, you have to manually specify them every time
-DEFAULT_SURICATA_SERVER="claret"  # -
-DEFAULT_TREX_SERVER="trex2"       # -
-DEFAULT_TREX_PORT1="0000:b3:00.0" # -
-DEFAULT_TREX_PORT2="0000:b3:00.1" # -
-DEFAULT_PCIES="0000:3b:00.0"      # -
+DEFAULT_SURICATA_SERVER="claret"        # -  (-s)
+DEFAULT_TREX_SERVER="trex2"             # -  (-tg)
+DEFAULT_TREX_PORT1="0000:b3:00.0"       # -  (-p1)
+DEFAULT_TREX_PORT2="0000:b3:00.1"       # -  (-p2)
+DEFAULT_PCIES="0000:3b:00.0"            # -  (-p, space-separated for multiple)
 
 # Mandatory for single port tests
-DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38" # -
-
-# Optional flags
-DEFAULT_TARGET_VLAN=15                     # -
-DEFAULT_TESTS="http_simple nfs_smb_simple" # all tests by default
-DEFAULT_TIME=300
-DEFAULT_HEATUP=0
-DEFAULT_HUGEPAGES="6G"
-LOGLEVEL="INFO"
+DEFAULT_TARGET_MAC="08:C0:EB:88:C5:38"  # -  (-tm)
+
+# Optional flags (if unset, the built-in defaults shown apply)
+DEFAULT_TARGET_VLAN=0                        # -  (-tv; untagged by default)
+DEFAULT_TESTS="http_simple nfs_smb_simple"   #    (-d; http_simple by default)
+DEFAULT_TIME=300                             #    (-t)
+DEFAULT_HEATUP=0                             #    (-ht)
+DEFAULT_HUGEPAGES="6G"                       #    (-sh)
+LOGLEVEL="INFO"                              #    (-sl)
+DEFAULT_SUITE_LOG_FILE=false                 #    (-sf; set to true to enable)
 ```
 
 Note that an empty string ("") in `-d` (or `DEFAULT_TESTS`) is a valid value for running all tests

pytest_start.sh

@@ -14,50 +14,90 @@ set -xe
 
 usage(){
   set +x
-  echo "Bash script to start pytest"
-  echo "Options:"
-  echo "-s    | --server [SERVER] to specify the server, where Suricata will be running"
-  echo "-tm   | --target-mac [MAC_ADDRESS] to specify where to send traffic when not using ASTF TRex."
-  echo "-tv   | --target-vlan [VLAN_ID] to specify what VLAN tag to use for generated traffic."
-  echo '-d    | --defined-tests [TESTS] to specify tests, which have to be included, for all available tests run [-d|--defined-tests] " ",
-  for specific tests: [-d|--defined-tests] "nfs_smb_simple https_simple" or use multiple parameter specification, for specific test from test file
-  use [-d|--defined-tests] https_simple/test_https_simple.py::test_https_simple, by default it runs http_simple tests'
-  echo "-t    | --defined-time [TIME] to specify traffic duration in tests (seconds)"
-  echo "-tg   | --trex-server-hostname [TRAFFIC GENERATOR] to specify traffic generator server for testing"
-  echo "-p1   | --trex-server-port-1 [TRAFFIC GENERATOR PORT] to specify traffic generator port"
-  echo "-p2   | --trex-server-port-2 [TRAFFIC GENERATOR PORT] to specify traffic generator port"
-  echo "-p    | --pcie [PCIE] to specify, on which pcie will be Suricata tested, use multiple parameter specification or [-p|--pcie] "0000:3b:00.0 0000:3b:00.1""
-  echo "-ht   | --heatup [TIME] to specify the duration for which to wait before measuring statistics"
-  echo "-f    | --filter [rules/norules] starts Suricata with/without rules"
-  echo "-pc   | --pcap [PATH] to specify the pcap file to send to Suricata. Also sets --defined-tests to *only* pcap_replay"
-  echo "-pm   | --prefer-trex-mode [MODE] to suggest a mode for TRex. If unavailable tests use their defaults."
-  echo "-fm   | --force-trex-mode [MODE] to force a TRex mode. If unavailable tests get skipped. Overrides -pm"
-  echo "-sb   | --trex-stl-burst [PPS] [COUNT] to send a fixed burst of COUNT packets at PPS in STL mode. Defaults: 200 000 PPS, 10 000 000 packets"
-  echo "-sh   | --suricata-hugepages [SIZE] to specify how much RAM to allocate in hugepages. Default is 6G."
-  echo "-fpu  | --force-pcap-upload to force re-upload of pcaps to the TRex server, even if identical files already exist."
-  echo "-sl   | --suite-log-level [LEVEL] to set the logging level for the test suite: a name (DEBUG, INFO, PROGRESS, WARNING, ERROR, CRITICAL) or a number (e.g. 25). Default: INFO"
-  echo "-sf   | --suite-log-file to enable writing suite logs to results/artefacts/<run>/pytest.log"
-  echo "-rl   | --run-label [LABEL] to set a custom name for the results directory, e.g. experimental-pr-1234-300s. Results are saved to results/artefacts/<label>/ instead of the default timestamp."
-  echo "-bs   | --binary-search <mm> <xm> <dr> <pr> to enable automatic throughput search"
-  echo "-bsh  | --binary-search-help to show help for binary search mode"
+  cat <<'EOF'
+Bash script to start pytest
+
+Usage:
+  ./pytest_start.sh [options]
+
+Connection:
+  -s    --server [SERVER]              Server where Suricata will be running
+  -tg   --trex-server-hostname [HOST]  Traffic generator server for testing
+  -p1   --trex-server-port-1 [PORT]    Traffic generator port 1
+  -p2   --trex-server-port-2 [PORT]    Traffic generator port 2
+  -p    --pcie [PCIE ...]              PCIe address(es) of the Suricata
+                                        interface(s), e.g. -p "0000:3b:00.0 0000:3b:00.1"
+
+Test selection:
+  -d    --defined-tests [TESTS ...]    Tests to run. For all available tests
+                                        run -d " "; for specific tests use
+                                        -d "nfs_smb_simple https_simple"; for a
+                                        specific test use
+                                        -d https_simple/test_https_simple.py::test_https_simple.
+                                        Default: http_simple tests
+  -t    --defined-time [TIME]          Traffic duration in seconds (default: 300)
+  -ht   --heatup [TIME]                Seconds to wait before measuring statistics
+  -f    --filter [rules/norules]       Start Suricata with/without rules
+  -pc   --pcap [PATH]                  Pcap file to send to Suricata. Also sets
+                                        --defined-tests to *only* pcap_replay
+
+Traffic:
+  -tm   --target-mac [MAC_ADDRESS]     Where to send traffic when not using ASTF TRex
+  -tv   --target-vlan [VLAN_ID]        VLAN tag to use for generated traffic (default: 0)
+  -pm   --prefer-trex-mode [MODE]      Suggest a mode for TRex. If unavailable,
+                                        tests use their defaults
+  -fm   --force-trex-mode [MODE]       Force a TRex mode. If unavailable, tests get
+                                        skipped. Overrides -pm
+  -sb   --trex-stl-burst [PPS] [COUNT] Send a fixed burst of COUNT packets at PPS
+                                        in STL mode.
+                                        Defaults: 200 000 PPS, 10 000 000 packets
+
+Suricata:
+  -sh   --suricata-hugepages [SIZE]    How much RAM to allocate in hugepages (default: 6G)
+
+Results and logging:
+  -sl   --suite-log-level [LEVEL]      Logging level for the suite: a name (DEBUG,
+                                        INFO, PROGRESS, WARNING, ERROR, CRITICAL)
+                                        or a number (e.g. 25). Default: INFO
+  -sf   --suite-log-file               Write suite logs to results/artefacts/<run>/pytest.log
+  -rl   --run-label [LABEL]            Custom name for the results directory, e.g.
+                                        experimental-pr-1234-300s. Results are saved to
+                                        results/artefacts/<label>/ instead of the
+                                        default timestamp
+  -fpu  --force-pcap-upload            Force re-upload of pcaps to the TRex server,
+                                        even if identical files already exist
+
+Advanced:
+  -bs   --binary-search <mm> <xm> <dr> <pr>
+                                        Enable automatic throughput search
+  -bsh  --binary-search-help           Show help for binary search mode
+
+Defaults for all options can also be set in a .env file in the repository
+root; see .env.example for the full list of variables
+(DEFAULT_SURICATA_SERVER, DEFAULT_TREX_SERVER, DEFAULT_TREX_PORT1, DEFAULT_TREX_PORT2,
+DEFAULT_PCIES, DEFAULT_TARGET_MAC, DEFAULT_TARGET_VLAN, DEFAULT_TESTS, DEFAULT_TIME, DEFAULT_HEATUP,
+DEFAULT_HUGEPAGES, DEFAULT_SUITE_LOG_FILE, LOGLEVEL).
+EOF
   exit 0
 }
 
 binary_search_usage(){
   set +x
-  echo "Bash script to start pytest"
-  echo "Binary search mode"
-  echo "Usage:"
-  echo "  -bs | --binary-search <mm> <xm> <dr> <pr>"
-  echo ""
-  echo "Positional arguments:"
-  echo "  mm  | min-multiplier  [FLOAT]  Lowest bound of the search range. (required)"
-  echo "  xm  | max-multiplier  [FLOAT]  Highest bound of the search range. (required)"
-  echo "  dr  | drop-rate       [FLOAT]  Max allowed drop rate in % <0,100>. (required)"
-  echo "  pr  | precision       [FLOAT]  Exit when (xm - mm) < precision. (required)"
-  echo ""
-  echo "Examples:"
-  echo "  -bs 0.0 10.0 1.0 0.05"
+  cat <<'EOF'
+Bash script to start pytest - binary search mode
+
+Usage:
+  -bs | --binary-search <mm> <xm> <dr> <pr>
+
+Positional arguments:
+  mm  | min-multiplier  [FLOAT]  Lowest bound of the search range. (required)
+  xm  | max-multiplier  [FLOAT]  Highest bound of the search range. (required)
+  dr  | drop-rate       [FLOAT]  Max allowed drop rate in % <0,100>. (required)
+  pr  | precision       [FLOAT]  Exit when (xm - mm) < precision. (required)
+
+Examples:
+  -bs 0.0 10.0 1.0 0.05
+EOF
   exit 0
 }