test(functional): optionally keep containers running post-tests

Additionally updates token creation to make use of `first_or_create()`,
to avoid errors from the script caused by GitLab constraints preventing
duplicate tokens with the same value.

3 files changed, 39 insertions, 1 deletions

diff --git a/README.rst b/README.rst
index 36f0180..63df02c 100644
--- a/README.rst
+++ b/README.rst
@@ -186,6 +186,21 @@ To run these tests:
    # run the python API tests:
    tox -e py_func_v4
 
+When developing tests it can be a little frustrating to wait for GitLab to spin
+up every run. To prevent the containers from being cleaned up afterwards, pass
+`--keep-containers` to pytest, i.e.:
+
+.. code-block:: bash
+
+   tox -e py_func_v4 -- --keep-containers
+
+If you then wish to test against a clean slate, you may perform a manual clean
+up of the containers by running:
+
+.. code-block:: bash
+
+   docker-compose -f tests/functional/fixtures/docker-compose.yml -p pytest-python-gitlab down -v
+
 By default, the tests run against the latest version of the ``gitlab/gitlab-ce``
 image. You can override both the image and tag by providing either the
 ``GITLAB_IMAGE`` or ``GITLAB_TAG`` environment variables.
diff --git a/tests/functional/conftest.py b/tests/functional/conftest.py
index 5d3b1b9..2c38b9f 100644
--- a/tests/functional/conftest.py
+++ b/tests/functional/conftest.py
@@ -50,6 +50,14 @@ def pytest_report_collectionfinish(config, startdir, items):
     ]
 
 
+def pytest_addoption(parser):
+    parser.addoption(
+        "--keep-containers",
+        action="store_true",
+        help="Keep containers running after testing",
+    )
+
+
 @pytest.fixture(scope="session")
 def temp_dir():
     return Path(tempfile.gettempdir())
@@ -66,6 +74,21 @@ def docker_compose_file(test_dir):
 
 
 @pytest.fixture(scope="session")
+def docker_compose_project_name():
+    """Set a consistent project name to enable optional reuse of containers."""
+    return "pytest-python-gitlab"
+
+
+@pytest.fixture(scope="session")
+def docker_cleanup(request):
+    """Conditionally keep containers around by overriding the cleanup command."""
+    if request.config.getoption("--keep-containers"):
+        # Print version and exit.
+        return "-v"
+    return "down -v"
+
+
+@pytest.fixture(scope="session")
 def check_is_alive():
     """
     Return a healthcheck function fixture for the GitLab container spinup.
diff --git a/tests/functional/fixtures/set_token.rb b/tests/functional/fixtures/set_token.rb
index 735dcd5..503588b 100644
--- a/tests/functional/fixtures/set_token.rb
+++ b/tests/functional/fixtures/set_token.rb
@@ -2,7 +2,7 @@
 
 user = User.find_by_username('root')
 
-token = user.personal_access_tokens.create(scopes: [:api, :sudo], name: 'default');
+token = user.personal_access_tokens.first_or_create(scopes: [:api, :sudo], name: 'default');
 token.set_token('python-gitlab-token');
 token.save!