#10 add fixtures

pytest-saas/README.md

@@ -15,3 +15,43 @@ To install the pytest-exasol-saas plugin, you can use pip:
 ```shell
 pip install pytest-exasol-saas
 ```
+
+## Database Instances
+
+### Using an Existing Database Instance
+
+By default the fixtures in pytest-exasol-saas Plugin will create instances of Exasol SaaS database with scope `session`.
+
+If you want to use an existing instance instead, then you can provide the instance's ID with command line option `--saas-database-id <ID>` to pytest.
+
+### Keeping Database Instances After the Test Session
+
+By default the fixtures in pytest-exasol-saas Plugin will remove the created database instances after the session or in case of errors.
+
+However, if you provide command line option `--keep-saas-database` then pytest-exasol-saas Plugin will _keep_ these instances for subsequent inspection or reuse.
+
+Please note hat long-running instances will cause significant costs.
+
+### Naming Database Instances
+
+pytest-exasol-saas Plugin will name the database instances using 3 components
+
+* **Project Short Tag**: Abbreviation of the current project, see below for different [options for providing the project short tag](#options-for-providing-the-project-short-tag).
+* **Timestamp**: Number of seconds since epoc, see [Unix Time](https://en.wikipedia.org/wiki/Unix_time).
+* A dash character `-`
+* **User Name**: Login name of the current user.
+
+A database instances might for example have the name `1715155224SAPIPY-run` indicating it was
+* created on Wednesday, May 8, 2024
+* in the context of a project with short tag `SAPYPI`
+* by a user with login name starting with `run`
+
+Please note that Exasol SaaS limits the length of database names to 10 characters only. So pytest-exasol-saas plugin will shorten the constructed name to 10 characters max.
+
+If running your tests on a server for Continuous Integration (CI) then the name of the user might be not very expressive.
+
+### Options for providing the Project Short Tag
+
+* In yaml file `error_code_config.yml` in the project's root directory
+* CLI option `--project-short-tag <short tag>` to pytest
+* Environment variable `PROJECT_SHORT_TAG`

pytest-saas/doc/changes/unreleased.md

@@ -9,3 +9,4 @@ This version introduces the `pytest-exasol-saas` plugin providing pytest functio
 ## Features
 
 * #9: Added sub-project for exasol-saas-api
+* #10: Added pytest fixtures for usage in integration tests of external projects

pytest-saas/exasol/pytest_saas/__init__.py

@@ -0,0 +1,100 @@
+import os
+from pathlib import Path
+
+import pytest
+from exasol.saas.client import openapi
+from exasol.saas.client.api_access import (
+    OpenApiAccess,
+    create_saas_client,
+    timestamp_name,
+)
+
+import exasol.pytest_saas.project_short_tag as pst
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        f"--saas-database-id",
+        help="""ID of the instance of an existing SaaS database to be
+            used during the current pytest session instead of creating a
+            dedicated instance temporarily.""",
+    )
+    parser.addoption(
+        f"--keep-saas-database",
+        action="store_true",
+        default=False,
+        help="""Keep the SaaS database instance created for the current
+            pytest session for subsequent inspection or reuse.""",
+    )
+    parser.addoption(
+        f"--project-short-tag",
+        help="""Short tag aka. "abbreviation" for your current project.
+            See docstring in project_short_tag.py for more details.
+            pytest plugin for exasol-saas-api will include this short tag into
+            the names of created database instances.""",
+    )
+
+
+def _env(var: str) -> str:
+    result = os.environ.get(var)
+    if result:
+        return result
+    raise RuntimeError(f"Environment variable {var} is empty.")
+
+
+@pytest.fixture(scope="session")
+def saas_host() -> str:
+    return _env("SAAS_HOST")
+
+
+@pytest.fixture(scope="session")
+def saas_pat() -> str:
+    return _env("SAAS_PAT")
+
+
+@pytest.fixture(scope="session")
+def saas_account_id() -> str:
+    return _env("SAAS_ACCOUNT_ID")
+
+
+@pytest.fixture(scope="session")
+def project_short_tag(request):
+    return (
+        request.config.getoption("--project-short-tag")
+        or os.environ.get("PROJECT_SHORT_TAG")
+        or pst.read_from_yaml(request.config.rootpath)
+    )
+
+
+@pytest.fixture(scope="session")
+def database_name(project_short_tag):
+    return timestamp_name(project_short_tag)
+
+
+@pytest.fixture(scope="session")
+def api_access(saas_host, saas_pat, saas_account_id) -> OpenApiAccess:
+    with create_saas_client(saas_host, saas_pat) as client:
+        yield OpenApiAccess(client, saas_account_id)
+
+
+@pytest.fixture(scope="session")
+def saas_database(
+    request, api_access, database_name
+) -> openapi.models.database.Database:
+    """
+    Note: The SaaS instance database returned by this fixture initially
+    will not be operational. The startup takes about 20 minutes.
+    """
+    db_id = request.config.getoption("--saas-database-id")
+    if db_id:
+        yield api_access.get_database(db_id)
+        return
+    with api_access.database(database_name) as db:
+        yield db
+
+
+@pytest.fixture(scope="session")
+def operational_saas_database_id(api_access, saas_database) -> str:
+    db = saas_database
+    api_access.wait_until_running(db.id)
+    return db.id

pytest-saas/exasol/pytest_saas/project_short_tag.py

@@ -0,0 +1,30 @@
+"""
+A "Project Short Tag" is a short abbreviation for a project.
+
+The pytest plugin for exasol-saas-api will include this short tag into the
+names of created database instances to enable identifying the origin of
+potentially long-running database instances in order to avoid unwanted costs.
+"""
+
+from pathlib import Path
+
+FILE = "error_code_config.yml"
+
+
+def read_from_yaml(dir: Path) -> str:
+    """
+    Read project-short-tag from yaml file ``FILE`` in the specified
+    directory ``dir``.
+    """
+    config_file = dir / FILE
+    if not config_file.exists():
+        return None
+    content = config_file.read_text()
+    header = False
+    for line in content.splitlines():
+        line = line.strip()
+        if header:
+            return line.strip().replace(":", "")
+        if line.startswith("error-tags:"):
+            header = True
+    raise RuntimeError(f"Could not read project short tag from file {config_file}")

pytest-saas/test/integration/pytest_saas_test.py

@@ -0,0 +1,116 @@
+import os
+import re
+from inspect import cleandoc
+from unittest import mock
+
+import pytest
+
+pytest_plugins = "pytester"
+
+
+@pytest.fixture
+def make_test_files():
+    def make(pytester, files):
+        pytester.makepyfile(**files)
+
+    return make
+
+
+def _testfile(body):
+    testname = re.sub(r"^.*def ([^(]+).*", "\\1", body, flags=re.S)
+    return { testname: cleandoc(body) }
+
+
+def _cli_args(*args):
+    return args
+
+
+def _env(**kwargs):
+    return kwargs
+
+
+@pytest.mark.parametrize(
+    "files,cli_args",
+    [
+        ( _testfile("""
+          def test_no_cli_args(request):
+              assert not request.config.getoption("--keep-saas-database")
+              assert request.config.getoption("--saas-database-id") is None
+          """),
+          _cli_args(),
+         ),
+        ( _testfile("""
+          import os
+          def test_cli_args(request):
+              assert request.config.getoption("--keep-saas-database")
+              assert "123" == request.config.getoption("--saas-database-id")
+              assert "PST" == request.config.getoption("--project-short-tag")
+          """),
+          _cli_args(
+              "--keep-saas-database",
+              "--project-short-tag", "PST",
+              "--saas-database-id", "123",
+          ),
+         ),
+    ])
+def test_pass_options_via_cli(pytester, make_test_files, files, cli_args):
+    make_test_files(pytester, files)
+    result = pytester.runpytest(*cli_args)
+    assert result.ret == pytest.ExitCode.OK
+
+
+@pytest.mark.parametrize(
+    "pst_file, pst_env, pst_cli, expected",
+    [
+        ("F", None, None, "F"),
+        ("F", "E",  None, "E"),
+        ("F", "E",  "C",  "C"),
+    ])
+def test_project_short_tag(
+        request,
+        pytester,
+        pst_file,
+        pst_env,
+        pst_cli,
+        expected,
+):
+    """
+    This test sets different values for project short tag in file
+    error_code_config.yml, cli option --project-short-tag, and environment
+    variable PROJECT_SHORT_TAG and verifies the precedence.
+    """
+    if pst_file:
+        pytester.makefile(".yml", **{
+            "error_code_config":
+            cleandoc(f"""
+            error-tags:
+              {pst_file}:
+                highest-index: 0
+            """)
+        })
+    pytester.makepyfile(** _testfile(
+        f"""
+        def test_project_short_tag(project_short_tag):
+            assert "{expected}" == project_short_tag
+        """))
+    env = { "PROJECT_SHORT_TAG": pst_env } if pst_env else {}
+    cli_args = [ "--project-short-tag", pst_cli ] if pst_cli else []
+    with mock.patch.dict(os.environ, env):
+        result = pytester.runpytest(*cli_args)
+    assert result.ret == pytest.ExitCode.OK
+
+
+def test_id_of_existing_database(request, pytester, capsys):
+    """
+    Use an invalid ID and verify that exasol-saas-api signals an error
+    because that there is no database with the specified ID.
+    """
+    testname = request.node.name
+    pytester.makepyfile(** _testfile( f"""
+          def {testname}(saas_database):
+              pass
+          """))
+    result = pytester.runpytest("--saas-database-id", "123")
+    captured = capsys.readouterr()
+    assert result.ret != pytest.ExitCode.OK
+    assert "Database not found" in captured.out