plugin

ensembl.utils.plugin

Ensembl's pytest plugin with useful unit testing hooks and fixtures.

DBFactory: TypeAlias = Callable[[StrPath | None, str | None, MetaData | None], UnitTestDB] module-attribute

fixture_assert_files()

Returns a function that asserts if two text files are equal, or prints their differences.

Source code in src/ensembl/utils/plugin.py

@pytest.fixture(name="assert_files")
def fixture_assert_files() -> Callable[[StrPath, StrPath], None]:
    """Returns a function that asserts if two text files are equal, or prints their differences."""

    def _assert_files(result_path: StrPath, expected_path: StrPath) -> None:
        """Asserts if two files are equal, or prints their differences.

        Args:
            result_path: Path to results (test-made) file.
            expected_path: Path to expected file.

        """
        with open(result_path, "r") as result_fh:
            results = result_fh.readlines()
        with open(expected_path, "r") as expected_fh:
            expected = expected_fh.readlines()
        files_diff = list(
            unified_diff(
                results,
                expected,
                fromfile=f"Test-made file {Path(result_path).name}",
                tofile=f"Expected file {Path(expected_path).name}",
            )
        )
        assert_message = f"Test-made and expected files differ\n{' '.join(files_diff)}"
        assert len(files_diff) == 0, assert_message

    return _assert_files

fixture_db_factory(request, data_dir)

Yields a unit test database factory.

Parameters:

Name	Type	Description	Default
request	FixtureRequest	Fixture that provides information of the requesting test function.	required
data_dir	Path	Fixture that provides the path to the test data folder matching the test's name.	required

Source code in src/ensembl/utils/plugin.py

@pytest.fixture(name="db_factory", scope="module")
def fixture_db_factory(request: FixtureRequest, data_dir: Path) -> Generator[DBFactory, None, None]:
    """Yields a unit test database factory.

    Args:
        request: Fixture that provides information of the requesting test function.
        data_dir: Fixture that provides the path to the test data folder matching the test's name.

    """
    created: dict[str, UnitTestDB] = {}
    server_url = request.config.getoption("server")

    def _db_factory(
        src: StrPath | None, name: str | None = None, metadata: MetaData | None = None
    ) -> UnitTestDB:
        """Returns a unit test database.

        Args:
            src: Directory path where the test database schema and content files are located, if any.
            name: Name to give to the new database. See `UnitTestDB` for more information.
            metadata: SQLAlchemy ORM schema metadata to populate the schema of the test database.

        """
        if src is not None:
            src_path = Path(src)
            if not src_path.is_absolute():
                src_path = data_dir / src_path
            db_key = name if name else src_path.name
            dump_dir: Path | None = src_path if src_path.exists() else None
        else:
            db_key = name if name else "dbkey"
            dump_dir = None
        return created.setdefault(
            db_key, UnitTestDB(server_url, dump_dir=dump_dir, name=name, metadata=metadata)
        )

    yield _db_factory
    # Drop all unit test databases unless the user has requested to keep them
    if not request.config.getoption("keep_dbs"):
        for test_db in created.values():
            test_db.drop()

local_data_dir(request)

Returns the path to the test data folder matching the test's name.

Parameters:

Name	Type	Description	Default
request	FixtureRequest	Fixture that provides information of the requesting test function.	required

Source code in src/ensembl/utils/plugin.py

@pytest.fixture(name="data_dir", scope="module")
def local_data_dir(request: FixtureRequest) -> Path:
    """Returns the path to the test data folder matching the test's name.

    Args:
        request: Fixture that provides information of the requesting test function.

    """
    return Path(request.module.__file__).with_suffix("")

pytest_addoption(parser)

Registers argparse-style options for Ensembl's unit testing.

Pytest initialisation hook <https://docs.pytest.org/en/latest/reference.html#_pytest.hookspec.pytest_addoption>_.

Parameters:

Name	Type	Description	Default
parser	Parser	Parser for command line arguments and ini-file values.	required

Source code in src/ensembl/utils/plugin.py

def pytest_addoption(parser: Parser) -> None:
    """Registers argparse-style options for Ensembl's unit testing.

    `Pytest initialisation hook
    <https://docs.pytest.org/en/latest/reference.html#_pytest.hookspec.pytest_addoption>`_.

    Args:
        parser: Parser for command line arguments and ini-file values.

    """
    # Add the Ensembl unitary test parameters to pytest parser
    group = parser.getgroup("Ensembl unit testing")
    group.addoption(
        "--server",
        action="store",
        metavar="URL",
        dest="server",
        required=False,
        default=os.getenv("DB_HOST", "sqlite:///"),
        help="Server URL where to create the test database(s)",
    )
    group.addoption(
        "--keep-dbs",
        action="store_true",
        dest="keep_dbs",
        required=False,
        help="Do not remove the test databases (default: False)",
    )

pytest_configure(config)

Allows plugins and conftest files to perform initial configuration.

More information: https://docs.pytest.org/en/latest/reference/reference.html#std-hook-pytest_configure

Parameters:

Name	Type	Description	Default
config	Config	The pytest config object.	required

Source code in src/ensembl/utils/plugin.py

def pytest_configure(config: Config) -> None:
    """Allows plugins and conftest files to perform initial configuration.

    More information: https://docs.pytest.org/en/latest/reference/reference.html#std-hook-pytest_configure

    Args:
        config: The pytest config object.

    """
    # Load server information
    server_url = make_url(config.getoption("server"))
    # If password set, treat it as an environment variable that needs to be resolved
    if server_url.password:
        server_url = server_url.set(password=os.path.expandvars(server_url.password))
        config.option.server = server_url.render_as_string(hide_password=False)

pytest_report_header(config)

Presents extra information in the report header.

Parameters:

Name	Type	Description	Default
config	Config	Access to configuration values, pluginmanager and plugin hooks.	required

Source code in src/ensembl/utils/plugin.py

def pytest_report_header(config: Config) -> str:
    """Presents extra information in the report header.

    Args:
        config: Access to configuration values, pluginmanager and plugin hooks.

    """
    # Show server information, masking the password value
    server = config.getoption("server")
    server = re.sub(r"(//[^/]+:).*(@)", r"\1xxxxxx\2", server)
    return f"server: {server}"

test_dbs(request, db_factory)

Returns a dictionary of unit test databases with the database name as key.

Requires a list of dictionaries, each with keys src, name and metadata, passed via request.param. At minimum either src or name needs to be provided. See db_factory() for details about each key's value.

This fixture is a wrapper of db_factory() intended to be used via indirect parametrization, for example::

from ensembl.core.models import Base
@pytest.mark.parametrize(
    "test_dbs",
    [
        [
            {"src": "core_db"},
            {"src": "core_db", "name": "human"},
            {"src": "core_db", "name": "cat", "metadata": Base.metadata},
        ]
    ],
    indirect=True
)
def test_method(..., test_dbs: dict[str, UnitTestDB], ...):

Parameters:

Name	Type	Description	Default
request	FixtureRequest	Fixture that provides information of the requesting test function.	required
db_factory	Callable	Fixture that provides a unit test database factory.	required

Source code in src/ensembl/utils/plugin.py

@pytest.fixture(scope="module")
def test_dbs(request: FixtureRequest, db_factory: Callable) -> dict[str, UnitTestDB]:
    """Returns a dictionary of unit test databases with the database name as key.

    Requires a list of dictionaries, each with keys `src`, `name` and `metadata`, passed via `request.param`.
    At minimum either `src` or `name` needs to be provided. See `db_factory()` for details about each key's
    value.

    This fixture is a wrapper of `db_factory()` intended to be used via indirect parametrization,
    for example::

        from ensembl.core.models import Base
        @pytest.mark.parametrize(
            "test_dbs",
            [
                [
                    {"src": "core_db"},
                    {"src": "core_db", "name": "human"},
                    {"src": "core_db", "name": "cat", "metadata": Base.metadata},
                ]
            ],
            indirect=True
        )
        def test_method(..., test_dbs: dict[str, UnitTestDB], ...):


    Args:
        request: Fixture that provides information of the requesting test function.
        db_factory: Fixture that provides a unit test database factory.

    """
    databases = {}
    for argument in request.param:
        src = argument.get("src", None)
        if src is not None:
            src = Path(src)
        name = argument.get("name", None)
        try:
            key = name or src.name
        except AttributeError as exc:
            raise TypeError("Expected at least 'src' or 'name' argument defined") from exc
        databases[key] = db_factory(src=src, name=name, metadata=argument.get("metadata"))
    return databases