diff --git a/README.md b/README.md index df51b9d..0185745 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,33 @@ -# Infrastructure Testing with ODC +[![PyPI version](https://img.shields.io/pypi/v/pytest-odc.svg)](https://pypi.org/project/pytest-odc) + +[![Python versions](https://img.shields.io/pypi/pyversions/pytest-odc.svg)](https://pypi.org/project/pytest-odc) + +# pytest-odc + +A [pytest](https://docs.pytest.org/) [plugin](https://docs.pytest.org/en/7.1.x/how-to/plugins.html) for simplifying [Open Datacube](https://www.opendatacube.org/) database tests. -Anyone writing applications using an ODC Database will need to be able to repeatedly test their code. This requires an ODC Database to contain a known set of data, every time the test is done. +# Testing Open Datacube Applications + +Anyone writing applications using an ODC Database needs to be able to test their code. This requires an ODC Database containing a known set of data. There's two challenges here: - - Having an ODC Database requires a private database in a PostgreSQL server somewhere, which is a challenge to set up. - - The database needs to be wiped and reset every time a test is run, to make it repeatable. + +- ODC requires a PostgreSQL server accessible anywhere test are run, which can be challenging to set up. +- The database should be reset every time a test is run, to make it possible to repeatedly run tests. ## The Solution -Included with ODC Core (soon!) are some [pytest](https://docs.pytest.org/) [fixtures](https://docs.pytest.org/en/stable/explanation/fixtures.html), which make it easy to write test code against an ODC Database. +This package provides reusable [pytest](https://docs.pytest.org/) [fixtures](https://docs.pytest.org/en/stable/explanation/fixtures.html), to make it easy to write test code against an ODC Database. It handles starting and stopping a temporary PostgreSQL server using Docker, initialising it for ODC use, and loading/wiping sets of test data on a per test module basis. ### Steps to Create New Tests -1. Copy the [ODC Test Plugin](https://github.com/opendatacube/datacube-explorer/blob/develop/cubedash/testutils/database.py) into your application code. +1. Install the [ODC Test Plugin](https://github.com/opendatacube/datacube-explorer/blob/develop/cubedash/testutils/database.py) into your Python environment. + + `pip install pytest-odc` -2. Create at least one each of a Metadata Type, Product and Dataset YAML file. These will be loaded into an ODC Database before your test code runs. +2. Create at least one each of an ODC [Metadata Type](https://datacube-core.readthedocs.io/en/latest/installation/metadata-types.html), [Product](https://datacube-core.readthedocs.io/en/latest/installation/product-definitions.html) and [Dataset](https://datacube-core.readthedocs.io/en/latest/installation/dataset-documents.html) YAML files. These will be loaded into an ODC Database before your test code runs. -3. Create a [pytest](https://docs.pytest.org/) Python file using this template: +3. Create a [pytest](https://docs.pytest.org/) file using this template: ```python """ @@ -39,69 +50,38 @@ Included with ODC Core (soon!) are some [pytest](https://docs.pytest.org/) [fixt assert len(my_datasets) == 3 ``` -4. Install extra test dependencies. - - ```console - $ pip install docker - ``` - -5. Create and activate a local environment. - - ```console - $ mamba create -p ./testenv python=3.10 datacube pytest docker-py - $ mamba activate /home/omad/dev/tmp-odc-testing/testenv - ``` +4. Run your new tests. - Note: the conda-forge package is called `docker-py`, the PyPI package is simply `docker`. + pytest tests/ -6. Run the example tests +# More Details / How it Works - pytest tests/ +The four provided pytest fixtures compose together to ensure an ODC Database is available and preloaded with test data for each test module. -## How it Works -pytest-odc -========== +## Fixtures -[![PyPI version](https://img.shields.io/pypi/v/pytest-odc.svg)](https://pypi.org/project/pytest-odc) - -[![Python versions](https://img.shields.io/pypi/pyversions/pytest-odc.svg)](https://pypi.org/project/pytest-odc) - -[![See Build Status on AppVeyor](https://ci.appveyor.com/api/projects/status/github/omad/pytest-odc?branch=master)](https://ci.appveyor.com/project/omad/pytest-odc/branch/master) - -A pytest plugin for simplifying ODC database tests +### `postgresql_server` ------------------------------------------------------------------------- +This fixture either: -This [pytest](https://github.com/pytest-dev/pytest) plugin was generated -with [Cookiecutter](https://github.com/audreyr/cookiecutter) along with -[\@hackebrot](https://github.com/hackebrot)\'s -[cookiecutter](https://github.com/pytest-dev/cookiecutter) -template. +- Runs a temporary PostgreSQL server using Docker +- Or checks that a test PostgreSQL server is already available via the `ODC_TEST_DB_URL` environment variable. -Features --------- +### `odc_db` -- TODO +This fixture provides a `datacube.Datacube()` object configured to connect to the temporary test database. -Requirements ------------- - -- TODO +It can be added to the parameters for a test for getting access to the temporary database. -Installation ------------- +### `odc_test_db` -You can install \"pytest-odc\" via -[pip](https://pypi.org/project/pip/) from -[PyPI](https://pypi.org/project): +This fixture creates all the ODC Database tables. - $ pip install pytest-odc +### `auto_odc_db` -Usage ------ +This fixture should be used as a `pytestmark autoload`, marking the test module as having variables named `METADATA_TYPES`, `PRODUCTS` and `DATASETS` being lists of files to load into the test database. -- TODO Contributing ------------ @@ -123,3 +103,13 @@ Issues If you encounter any problems, please [file an issue](https://github.com/omad/pytest-odc/issues) along with a detailed description. + +Release Process +--------------- + +``` +rm -rf dist/ +python -m build +twine upload --repository testpypi dist/* +twine upload dist/* +```