Local integration testing updates

.github/integration-test.py

@@ -226,12 +226,35 @@ def main():
     copy_parser.add_argument("src")
     copy_parser.add_argument("dest")
 
-    run_test_parser = subparsers.add_parser("run-test")
-    run_test_parser.add_argument("--installer-args", action="append")
-    run_test_parser.add_argument("--upgrade-from", default="")
-    run_test_parser.add_argument("--bootstrap-pip-spec", default="/srv/src")
-    run_test_parser.add_argument("container_name")
-    run_test_parser.add_argument("test_files", nargs="+")
+    run_test_parser = subparsers.add_parser(
+        "run-test",
+        help="Runs the bootstrap script in a container, then executes specified integration tests.",
+    )
+    run_test_parser.add_argument(
+        "--installer-args",
+        action="append",
+        default=[],
+        help="Additional arguments to pass to bootstrap.py during the main installation. Can be used multiple times.",
+    )
+    run_test_parser.add_argument(
+        "--upgrade-from",
+        default="",
+        help="A version/tag (e.g., 'main', 'v0.1.0') to install first, simulating an upgrade to the current source code.",
+    )
+    run_test_parser.add_argument(
+        "--bootstrap-pip-spec",
+        default="/srv/src",
+        help="The pip specification used by the bootstrap script to install TLJH (for example: '--bootstrap-pip-spec=git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name'). Defaults to the local source code path.",
+    )
+    run_test_parser.add_argument(
+        "container_name",
+        help="An identifier for the container/test run (for example: 'basic-tests').",
+    )
+    run_test_parser.add_argument(
+        "test_files",
+        nargs="+",
+        help="A list of one or more test files under 'integration-tests/' to be executed.",
+    )
 
     show_logs_parser = subparsers.add_parser("show-logs")
     show_logs_parser.add_argument("container_name")

docs/contributing/tests.md

@@ -28,35 +28,43 @@ against the same installation of TLJH.
 
 ### Running integration tests locally
 
-You need `docker` installed and callable by the user running
-the integration tests without needing sudo.
+You need `docker` or `podman` installed and callable by the user
+running the integration tests without needing sudo.
 
-You can then run the tests with:
+First build the container with a Ubuntu-based image:
 
 ```bash
-.github/integration-test.py run-test <name-of-run> <test-file-names>
+.github/integration-test.py build-image \
+  --build-arg "BASE_IMAGE=ubuntu:22.04"
 ```
 
-- `<name-of-run>` is an identifier for the tests - you can choose anything you want
-- `<test-file-names>>` is list of test files (under `integration-tests`) that should be run in one go.
+Then you can then run the tests with the `run-test` function. For usage run:
+
+```bash
+.github/integration-test.py run-test --help
+```
 
 For example, to run all the basic tests, you would write:
 
 ```bash
 .github/integration-test.py run-test basic-tests \
-   test_hub.py \
-   test_proxy.py \
-   test_install.py \
-   test_extensions.py
+  test_hub.py \
+  test_proxy.py \
+  test_install.py \
+  test_extensions.py
 ```
 
-This will run the tests in the three files against the same installation
+This will run the tests in the four files against the same installation
 of TLJH and report errors.
 
-If you would like to run the tests with a custom pip spec for the bootstrap script, you can use the `--bootstrap-pip-spec`
+If you would like to run the tests with a custom `pip` spec for the bootstrap script, you can use the `--bootstrap-pip-spec`
 parameter:
 
 ```bash
-.github/integration-test.py run-test <name-of-run> <test-file-names> \
-   --bootstrap-pip-spec="git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name"
+.github/integration-test.py run-test custom-pip-spec \
+  test_hub.py \
+  test_proxy.py \
+  test_install.py \
+  test_extensions.py \
+  --bootstrap-pip-spec="git+https://github.com/your-username/the-littlest-jupyterhub.git@branch-name"
 ```