Streamline local test environment setup

.github/CONTRIBUTING.md

@@ -109,28 +109,65 @@ Code coverage is monitored for every PR and for the code base as a whole using [
 
 ### Running the Tests
 
+There are several ways to run the tests locally:
+
+#### 1. Using Composer Scripts (Recommended)
+
+The simplest way to run tests is using the Composer scripts:
+
+```bash
+# Run tests without coverage
+composer test
+
+# Run tests with coverage
+composer coverage
+
+# Run tests with automatic test server management
+composer test:withserver
+```
+
+#### 2. Manual Test Environment Management
+
+If you need more control over the test environment, you can manage it manually:
+
+```bash
+# Start all test servers and set environment variables
+# We need to source the script to properly set environment variables in our shell
+source scripts/start-test-environment.sh
+
+# Now run your tests
+composer test
+
+# When done, stop all servers
+./scripts/stop-test-environment.sh
+```
+
+Note: The environment scripts must be sourced (using `source` or `.`) to properly set environment variables in your shell.
+
+#### 3. Individual Component Control
+
+For debugging or development, you might want to manage individual components:
+
 ```bash
-# Start the test server
+# Just the test server
 PORT=8080 vendor/bin/start.sh
-export "REQUESTS_TEST_HOST_HTTP=localhost:8080"
+export REQUESTS_TEST_HOST_HTTP=localhost:8080
 
-# Start the proxy server
+# Just the proxy servers
 PORT=9002 tests/utils/proxy/start.sh
 PORT=9003 AUTH="test:pass" tests/utils/proxy/start.sh
-export "REQUESTS_HTTP_PROXY=localhost:9002"
-export "REQUESTS_HTTP_PROXY_AUTH=localhost:9003"
-export "REQUESTS_HTTP_PROXY_AUTH_USER=test"
-export "REQUESTS_HTTP_PROXY_AUTH_PASS=pass"
+export REQUESTS_HTTP_PROXY=localhost:9002
+export REQUESTS_HTTP_PROXY_AUTH=localhost:9003
+export REQUESTS_HTTP_PROXY_AUTH_USER=test
+export REQUESTS_HTTP_PROXY_AUTH_PASS=pass
+```
 
-# Run the tests
-composer test
+Remember to stop any servers you start:
 
-# Stop the proxy server
-PORT=9002 tests/utils/proxy/stop.sh
+```bash
+vendor/bin/stop.sh                   # Stop test server
+PORT=9002 tests/utils/proxy/stop.sh  # Stop proxy servers
 PORT=9003 tests/utils/proxy/stop.sh
-
-# Stop the test server
-vendor/bin/stop.sh
 ```
 
 To run the test with code coverage, use `composer coverage` instead.

composer.json

@@ -87,25 +87,29 @@
       "@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf"
     ],
     "test": [
-      "@php ./vendor/phpunit/phpunit/phpunit --no-coverage"
-    ],
-    "test10": [
-      "@php ./vendor/phpunit/phpunit/phpunit -c phpunit10.xml.dist --no-coverage"
+      "./scripts/run-phpunit.sh --no-coverage"
     ],
     "coverage": [
-      "@php ./vendor/phpunit/phpunit/phpunit"
+      "./scripts/run-phpunit.sh"
+    ],
+    "testserver:start": [
+      "./scripts/start-test-environment.sh"
+    ],
+    "testserver:stop": [
+      "./scripts/stop-test-environment.sh"
     ],
-    "coverage10": [
-      "@php ./vendor/phpunit/phpunit/phpunit -c phpunit10.xml.dist"
+    "test:withserver": [
+      "./scripts/run-tests-with-server.sh"
     ]
   },
   "scripts-descriptions": {
     "lint": "Lint PHP files to find parse errors.",
     "checkcs": "Check the entire codebase for code-style issues.",
     "fixcs": "Fix all auto-fixable code-style issues in the entire codebase.",
-    "test": "Run the unit tests on PHPUnit 5.x - 9.x without code coverage.",
-    "test10": "Run the unit tests on PHPUnit 10.x without code coverage.",
-    "coverage": "Run the unit tests on PHPUnit 5.x - 9.x with code coverage.",
-    "coverage10": "Run the unit tests on PHPUnit 10.x with code coverage."
+    "test": "Run the unit tests without code coverage (auto-detects PHPUnit version)",
+    "coverage": "Run the unit tests with code coverage (auto-detects PHPUnit version)",
+    "testserver:start": "Start the test environment including test server and proxy servers (Note: environment variables will only be available in a sourced shell)",
+    "testserver:stop": "Stop all running test environment servers",
+    "test:withserver": "Start test servers, run PHPUnit tests with appropriate config, then stop servers"
   }
 }

scripts/run-phpunit.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Detect PHPUnit version
+PHPUNIT_VERSION=$("${PROJECT_ROOT}/vendor/bin/phpunit" --version | grep --only-matching --max-count=1 --extended-regexp '\b[0-9]+\.[0-9]+')
+
+# Determine if we should include coverage based on argument
+COVERAGE_ARG=""
+if [ "$1" != "--no-coverage" ]; then
+    COVERAGE_ARG="--coverage-html build/coverage"
+fi
+
+# Run the tests with the appropriate config
+if printf '%s\n%s\n' "10.0" "$PHPUNIT_VERSION" | sort -V -C; then
+    "${PROJECT_ROOT}/vendor/bin/phpunit" -c phpunit10.xml.dist $COVERAGE_ARG
+else
+    "${PROJECT_ROOT}/vendor/bin/phpunit" $COVERAGE_ARG
+fi 

scripts/run-tests-with-server.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Source the environment setup
+source "${SCRIPT_DIR}/start-test-environment.sh" || exit 1
+
+# Run the tests
+"${SCRIPT_DIR}/run-phpunit.sh" --no-coverage
+TEST_EXIT_CODE=$?
+
+# Stop the test environment
+source "${SCRIPT_DIR}/stop-test-environment.sh"
+
+exit $TEST_EXIT_CODE 

scripts/start-test-environment-wrapper.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Get the directory of this script
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
+# Source the main script
+if source "${SCRIPT_DIR}/start-test-environment.sh"; then
+    exit 0
+else
+    exit 1
+fi 

scripts/start-test-environment.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+# Ensure the script is being sourced
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    echo "Error: This script must be sourced to set environment variables"
+    echo "Usage: source scripts/start-test-environment.sh"
+    exit 1
+fi
+
+# Store script dir for relative paths
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+PID_DIR="${PROJECT_ROOT}/.test-pids"
+
+# Check if mitmproxy is installed
+if ! command -v mitmdump &> /dev/null; then
+    echo "Error: mitmproxy is not installed. Please install it with: pip3 install mitmproxy"
+    return 1
+fi
+
+# Get mitmproxy version and compare with minimum required (using 9.0.0 as minimum)
+MITM_VERSION=$(mitmdump --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1)
+MINIMUM_VERSION="11.0.2"
+
+if ! printf '%s\n%s\n' "$MINIMUM_VERSION" "$MITM_VERSION" | sort -V -C; then
+    echo "Error: mitmproxy version $MITM_VERSION is too old"
+    echo "Please upgrade to version $MINIMUM_VERSION or newer with: pip3 install --upgrade mitmproxy"
+    return 1
+fi
+
+echo "Found mitmproxy version $MITM_VERSION"
+
+# Create directory for PID files if it doesn't exist
+mkdir -p "$PID_DIR"
+
+# Start the test server
+echo "Starting test server..."
+PORT=8080 "${PROJECT_ROOT}/vendor/bin/start.sh"
+echo $! > "${PID_DIR}/test-server.pid"
+export REQUESTS_TEST_HOST_HTTP=localhost:8080
+
+# Start proxy servers
+echo "Starting proxy servers..."
+PORT=9002 "${PROJECT_ROOT}/tests/utils/proxy/start.sh"
+echo $! > "${PID_DIR}/proxy-server.pid"
+
+PORT=9003 AUTH="test:pass" "${PROJECT_ROOT}/tests/utils/proxy/start.sh"
+echo $! > "${PID_DIR}/proxy-auth-server.pid"
+
+# Set environment variables
+export REQUESTS_HTTP_PROXY=localhost:9002
+export REQUESTS_HTTP_PROXY_AUTH=localhost:9003
+export REQUESTS_HTTP_PROXY_AUTH_USER=test
+export REQUESTS_HTTP_PROXY_AUTH_PASS=pass
+
+# Wait for servers to be ready
+echo "Waiting for servers to be ready..."
+sleep 2
+
+# Test server connections
+echo "Testing server connections..."
+curl -s -I http://localhost:8080 > /dev/null || { echo "Test server not responding"; return 1; }
+curl -s -I http://localhost:9002 > /dev/null || { echo "Proxy server not responding"; return 1; }
+
+echo "Test environment is ready!"
+echo "Environment variables set:"
+echo "REQUESTS_TEST_HOST_HTTP=localhost:8080"
+echo "REQUESTS_HTTP_PROXY=localhost:9002"
+echo "REQUESTS_HTTP_PROXY_AUTH=localhost:9003"
+
+return 0 

scripts/stop-test-environment.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+# Store script dir for relative paths
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+PID_DIR="${PROJECT_ROOT}/.test-pids"
+
+# Function to safely kill a process
+kill_process() {
+    local pid_file="$1"
+    if [ -f "$pid_file" ]; then
+        pid=$(cat "$pid_file")
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Stopping process $pid"
+            kill "$pid"
+            rm "$pid_file"
+        else
+            echo "Process $pid not running"
+            rm "$pid_file"
+        fi
+    fi
+}
+
+# Stop all servers
+echo "Stopping test environment..."
+
+# Stop test server
+kill_process "${PID_DIR}/test-server.pid"
+"${PROJECT_ROOT}/vendor/bin/stop.sh"
+
+# Stop proxy servers
+PORT=9002 "${PROJECT_ROOT}/tests/utils/proxy/stop.sh"
+kill_process "${PID_DIR}/proxy-server.pid"
+
+PORT=9003 "${PROJECT_ROOT}/tests/utils/proxy/stop.sh"
+kill_process "${PID_DIR}/proxy-auth-server.pid"
+
+# Clean up PID directory if empty
+rmdir "${PID_DIR}" 2>/dev/null || true
+
+echo "Test environment stopped"