Provide options to speed up test script (#415)

* Add pytest-xdist for multi CPU parallel testing
* Update instructions
* Fix createsuperuser.sh
* Add shell.sh, remove unneeded scripts

app/requirements.in

@@ -13,4 +13,5 @@ markdown
 psycopg2-binary
 pytest-cov
 pytest-django
+pytest-xdist
 tzdata

app/requirements.txt

@@ -32,6 +32,10 @@ djangorestframework==3.14.0
     #   drf-spectacular
 drf-jwt==1.19.2
 drf-spectacular==0.27.1
+exceptiongroup==1.2.2
+    # via pytest
+execnet==2.1.1
+    # via pytest-xdist
 flake8==7.0.0
 inflection==0.5.1
     # via drf-spectacular
@@ -72,8 +76,10 @@ pytest==8.0.2
     # via
     #   pytest-cov
     #   pytest-django
+    #   pytest-xdist
 pytest-cov==4.1.0
 pytest-django==4.8.0
+pytest-xdist==3.6.1
 pytz==2024.1
     # via djangorestframework
 pyyaml==6.0.1
@@ -88,6 +94,15 @@ rpds-py==0.18.0
     #   referencing
 sqlparse==0.4.4
     # via django
+tomli==2.1.0
+    # via
+    #   black
+    #   coverage
+    #   pytest
+typing-extensions==4.12.2
+    # via
+    #   asgiref
+    #   black
 tzdata==2024.1
 uritemplate==4.1.1
     # via drf-spectacular

docs/contributing/tools/scripts.md

@@ -31,7 +31,7 @@ These scripts assume you are using bash.
 
 1. **createsuperuser.sh** - create a default superuser
 
-    1. This assumes that `DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_PASSWORD` are set in `.env.dev`
+    1. This assumes that `DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_PASSWORD` are set in `.env.docker`
 
 1. **db.sh** - connect to the database in the `db` container
 
@@ -44,8 +44,6 @@ These scripts assume you are using bash.
 
 1. **lint.sh** - lint and and auto-format code
 
-1. **loadenv.sh** - load environment variables from `.env.dev` into shell environment
-
 1. **logs.sh** - view/tail container logs
 
 1. **migrate.sh** - run database migrations inside container
@@ -60,11 +58,14 @@ These scripts assume you are using bash.
 
     1. Pass in `-h` to show usage
 
-1. **start-local.sh** - start the development server natively
+1. **shell.sh** - open a shell on the terminal
+
+    1. Pass in `-h` to show usage
 
 1. **test.sh** - run tests and generate test coverage report
 
     1. Use the `-k` flag to filter tests. For example `test.sh -k program_area` will select only tests with "program_area" in the name.
-    1. Pass in `--no-cov` to disable the coverage report. The coverage report will show many missing lines of coverage as a result.
+    1. use `--help` to see other script options.
+    1. use `--help-pytest` to see pytest options that can be added.
 
 1. **update-dependencies.sh** - update python dependencies to the latest versions

scripts/path.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Note about -e: Intentionally not "set -e..." so that if there is a syntax error,
+# the shell will not close.  Unless you are joining commands with ||
+#
+# set -o pipefail will catch any failing command unless commands joined by ||
+# -u : errors if variable is not set
+# -o pipefail : script terminates if any command fails
+echo starting
+
+# Handle errors gracefully without exiting the shell session.
+
+
+# Main function to contain the logic.
+main() {
+
+  echo In main
+  if [[ "${BASH_SOURCE[0]}" != "${0}" ]]; then
+    echo "The script was sourced."
+  else
+    echo "Error: the script must be sourced."
+    return 1
+  fi
+  ORIGINAL_DIR=$PWD
+
+  if [ -f "path.sh" ]; then
+    echo path.sh is in current directory
+  elif [ -f "../scripts/path.sh" ]; then
+    echo "cd ../scripts"
+    cd ../scripts || return 1
+  elif [ -f "scripts/path.sh" ]; then
+    echo "cd scripts"
+    cd scripts || return 1
+  elif [ ! -f "path.sh" ]; then
+    echo "Could not find path.sh relative to the current directory."
+    return 1
+  fi
+
+  echo Checking path
+
+  if [[ "$PATH" = *"$PWD"* ]]; then
+    echo Path is already set
+  else
+    echo "Adding $PWD to PATH"
+    export PATH="$PATH:$PWD"
+  fi
+
+  echo "cd $ORIGINAL_DIR"
+  cd "$ORIGINAL_DIR" || return 1
+
+  echo "Script completed successfully."
+}
+
+# Run the main function.
+main

scripts/shell.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+echo "\q to quit"
+
+set -x
+docker-compose exec web run /bin/sh -e .env.docker

scripts/test.sh

@@ -1,13 +1,86 @@
 #!/bin/bash
 set -euo pipefail
 IFS=$'\n\t'
-set -x
+# Default options
+COVERAGE="--no-cov"
+EXEC_COMMAND=true
+CHECK_MIGRATIONS=true
+N_CPU="auto"
+PYTEST_ARGS=("")
 
-# check for missing migration files
-# https://adamj.eu/tech/2024/06/23/django-test-pending-migrations/
-docker-compose exec -T web python manage.py makemigrations --check
+# Function to display help
+show_help() {
+  cat << EOF
+Usage: ${0##*/} [OPTIONS] [pytest-args]
 
-# run tests and show code coverage
-# filter tests using -k <filter>
-# ex: test.sh -k program_area --no-cov
-docker-compose exec -T web pytest "$@"
+Options:
+  --coverage         Run tests with coverage (default: without coverage, using --no-cov).
+  --skip-migrations  Skip checking for pending migrations before running tests (default: check migrations).
+  -n                 Remove the default --nauto option for running tests (default: -n auto).  There must be
+                       a space after -n and the value.  (If you use 1 the script changes the value to 0.)
+  --help             Display this help message and exit.
+  --help-pytest      Display pytest help.
+
+Other parameters passed to the script will be forwarded to pytest as specified.
+
+By default:
+  - Tests run without coverage.
+  - Migrations are checked before running tests.
+  - Tests are run using --n auto for optimal parallel execution.
+EOF
+}
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  arg="$1" # Use $1 as the current argument
+  case $arg in
+    --help)
+      show_help
+      exit 0
+      ;;
+    --help-pytest)
+      pytest --help
+      exit 0
+      ;;
+    --no-exec)
+      EXEC_COMMAND=false
+      ;;
+    --coverage)
+      COVERAGE=""  # Enable coverage
+      echo "Coverage enabled"
+      ;;
+    --skip-migrations)
+      CHECK_MIGRATIONS=false  # Skip migration checks
+      echo "Skipping migration checks"
+      ;;
+    -n)
+      shift
+      N_CPU="$1"
+      if [ "$N_CPU" == "1" ]; then
+        N_CPU=0
+      fi
+      ;;
+    *)
+      PYTEST_ARGS+=("$arg")  # Preserve other arguments for pytest
+      echo "Positional argument added: $arg"
+      echo "Current python args: ${PYTEST_ARGS[*]}"
+      ;;
+  esac
+  shift # Shift to the next argument
+done
+
+# Check for missing migration files if not skipped
+if [ "$CHECK_MIGRATIONS" = true ]; then
+  echo "Checking for missing migrations..."
+  set -x
+  docker-compose exec -T web python manage.py makemigrations --check
+  set +x
+fi
+
+if [ "$EXEC_COMMAND" = true ]; then
+  set -x
+  docker-compose exec -T web pytest -n "$N_CPU" $COVERAGE "${PYTEST_ARGS[@]}"
+  set +x
+else
+  echo docker-compose exec -T web pytest -n "$N_CPU" $COVERAGE "${PYTEST_ARGS[@]}"
+fi