| Name | testing-fixtures JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | |
| Summary | New approach to Python test fixtures (compatible with pytest) |
| upload_time | 2024-01-14 19:34:35 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
fixture
fixtures
testing
tests
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Beyond Pytest Fixtures
This repo contains an implementation of a new approach to fixtures for use with
`pytest`.
In addition we demonstrate how to use these new fixtures in both unit and
integration tests.
## Utility Fixtures
The library also comes with some utility fixtures that often come in handy.
For example `create_temp_dir`
(injects the `Path` to a temporary directory into the test using the fixture) and
`create_temp_cwd` (switches the cwd to a temporary directory and
injects its `Path` into the test).
## Project Evolution
The evolution of this project is being tracked in this [doc](./evolution.md).
## Advantages of `pytest` fixtures
`pytest` fixtures are extremely powerful and flexible.
- Provides a pythonic mechanism for setup, teardown, and injection of state into tests.
- Fixture scope is configurable allowing for heavy computation to be
carried out once per test function (default), test module or session.
- Allows fixtures to be composed which sets up a causal relation between fixtures and
sharing of state between multiple fixtures and the test function.
## Disadvantages of `pytest` fixtures
### Tunability
`pytest` fixtures lack a straight-forward mechanism for passing arguments to them from
the test function defition site.
It is not uncommon to require that a specific piece of state be injected before
running a specific test.
A "tunable" fixture would solve this requirement.
`pytest` solves this by *magically* allowing `pytest.mark.parametrize` values to be
passed through to a fixture being used by a test.
This is not obvious and uses a mechanism that is primarily used for
injecting multiple states into a test to create multiplicity.
### Importability
`pytest` recommends that fixtures be defined in a `conftest.py` file (a most non-obvious
name) and that they **not** be imported directly.
When tests are executed `pytest` parses `conftest.py` and magically inserts
the fixtures (setup, teardown, and interjection) into the test execution.
This is completely different from how the rest of Python operates and
is a source of great confusion to newcomers.
### Fixtures vs Injected Value
`pytest` fixtures overlap two distinct concepts when connecting a test function to
a fixture.
One is the name/handle to the fixture definition (generator function), and
the other is the variable inside the test function which is
bound to the value yielded by the fixture.
This over-use of a single name is evident every time one is choosing the name for
the fixture + variable.
Does one name it for the variable or for the operation that the fixture carries out
whose side-effect is the value in the varible e.g.
`add_portfolio` vs `portfolio_name`.
### Type Annotation
The way `pytest` *registers* fixtures and then *injects/interleaves* them into/with
test functions means it is practically impossible for a type engine to match and
enforce types between the fixture definition and the value injected into
the test function.
This is a source of considerable frustration for anyone who has gone through the
effort to annotate their code and their tests.
## Prototype
We provide a prototype for a new type of fixtures beyond what is provided by `pytest`.
### Objectives
- Works seamlessly with `pytest`.
- Importable from another module (no more `conftest.py`).
- Composable.
One fixture can be connected to another fixture and recieve a value from it.
- Tunable.
Fixtures definitions can declare parameters.
These parameters can either be provided at **either**
the test definition site **or**
inside the fixture definition module.
The value(s) provided to the parameter(s) will remain consistent throughout
the execution of any given test.
The same value will be visible to all participating entities:
the test function and all fixtures composed with said fixture.
- Fully typed and type-aware.
Provides enforceable bindings between fixture definitions,
values injected into fixtures, and
values injected from them into test functions.
### Interface
To achieve **all** of the objectives listed above the interface for these fixtures is
slightly more verbose than `pytest` fixtures while
being significantly less magical.
The following four decorators are provided for defining these fixtures:
1. `@fixture`: Applied to a fixture definition (one-shot generator function).
Creates an instance of the `Fixture` class.
**This instance is both a decorator as well as a
reusable and reentrant context manager.**
This instance is applied as a decorator to test functions and injects
the yielded value into it.
Example (extracted from `tests/unit/utils.py`):
```python
@fixture
def fixture_b(b1: Bi1, b2: Bi2) -> FixtureDefinition[Bo]:
"""A fixture that takes injected value from the test function decoration."""
yield Bo(b1=b1, b2=b2)
```
*Note* One can use `NewType` and `TypedDict` to constrain the fixture parameters and
the value it yields which allows for tightly binding the yielded value
to any location where it is used (test function or composed fixture).
Similarly the `FixtureDefinition[]` generic type constrains how the fixture is
allowed to be used.
Each instance has a `.set()` method which is used to provide values for
any parameters declared in the fixture definition.
`.set()` can be called on either the test function decoration site,
inside the module defining the fixture,
or while composing the fixture with another.
Examples (extracted from `tests/unit/utils.py` and
`tests/unit/test_new_fixtures.py`):
```python
@fixture_b.set(Bi1(42), Bi2(3.14))
def test_b(b: Bo) -> None:
"""Test parametrized fixture_b in isolation."""
assert b == {"b1": 42, "b2": 3.14}
```
or
```python
@fixture
@compose(fixture_b.set(Bi1(13), Bi2(1.44)))
def fixture_c(b: Bo) -> FixtureDefinition[Co]:
"""A fixture that takes an injected value from ANOTHER fixture."""
yield Co(c=b)
```
All fixture composition and test decoration creates a strict ordering of when the
fixture's context manager is entered and exited.
Only the value at the first entry is available throughout the execution of a single
test.
1. `@compose`: A function that takes a single argument which must be an instance of
`Fixture` and returns a decorator that is applied to another fixture definition.
Designed to be applied **before** the fixture definition is wrapped inside
`@fixture` (don't worry,
the type system will shout at you if you get the order wrong).
The value yielded by the composed fixture is injected as the first parameter of
the decorated fixture definition.
It essentially creates a simpler fixture definition with one less parameter.
Example:
```python
@fixture
@compose(fixture_b.set(Bi1(13), Bi2(1.44)))
def fixture_c(b: Bo) -> FixtureDefinition[Co]:
"""A fixture that takes an injected value from ANOTHER fixture."""
yield Co(c=b)
```
The composed fixture can also have its value set from the test site but
be available to the composition.
Example:
```python
@fixture
@compose(fixture_b)
def fixture_g(b: Bo, g: Gi) -> FixtureDefinition[Go]:
"""Fixture that uses a late-injected fixture_b and a value from the test site."""
yield {"b": b, "g": g}
@fixture_b.set(Bi1(56), Bi2(9.7))
@fixture_g.set(Gi(41))
def test_g(g: Go, b: Bo) -> None:
"""Inject args into fixture from test site and trickle down to pulled in fixture."""
assert b == {"b1": 56, "b2": 9.7}
assert g == {"b": b, "g": 41}
```
1. `@noinject`: Used at the test definition decoration site to wrap fixtures.
The wrapped fixture's yielded values will **not** be injected into the test function.
Example:
```python
@noinject(fixture_b.set(Bi1(75), Bi2(2.71)))
def test_b_no_injection() -> None:
"""The value yielded by fixture_b is NOT injected into the test."""
```
The type engine will understand *not* injecting and validates accordingly.
1. `@compose_noinject`: Applied to composed fixtures to *stop* them from injecting
their yielded value into the fixture they are composed with.
Example:
```python
@fixture
@compose_noinject(fixture_b.set(Bi1(39), Bi2(8.1)))
def fixture_h(h: Hi) -> FixtureDefinition[Ho]:
"""Fixture that uses a composed fixture_b but NOT its yielded value."""
yield Ho(h=h)
```
Again, the type engine is aware of the mechanics.
## Implementation
The implementation can be found in [testing.fixtures](./testing/fixtures).
It consists of nested decorators, modified context managers, and parameter injection,
all fully typed.
## Demo
### Integration Tests
To demonstrate this in action we have a REST server that:
- receives POST requests
- fetches data from a (postgres) database
- uses the fetched data to construct the response
This has been setup as a composable environment.
First build the local images: `docker-compose build`.
Then, run the tests: `docker-compose run --rm test`.
### Unit Tests
We have also provided a number of unit tests, unrelated to the REST server application,
which focus on demonstrating all the possible permutations of fixture usage,
composition, and state injection at both the test and fixture definition site.
## Local Development
To make changes to this code base the recommendation is to use a virtual env:
```console
python3.11 -m venv .venv
source .venv/bin/activate
pip install ".[dev]"
```
Your IDE should be able to now access this virtual env and
provide you with autocomplete, intellisense, etc.
## How to Deploy
1. Build the package: `python3.11 -m build`
This will create the source tarball and wheel in the `dist/` folder.
2. Deploy to pypi: `python3.11 -m twine upload dist/*`
Enter your pypi username and password.
Raw data
{
"_id": null,
"home_page": "",
"name": "testing-fixtures",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "fixture,fixtures,testing,tests",
"author": "",
"author_email": "\"Abid H. Mujtaba\" <abid.naqvi83@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/32/d0/e272c216119bf3e1d441a0f0651d2b97a34a9aba05fee7fdd1a5b6a00ca8/testing_fixtures-0.4.1.tar.gz",
"platform": null,
"description": "# Beyond Pytest Fixtures\n\nThis repo contains an implementation of a new approach to fixtures for use with\n`pytest`.\nIn addition we demonstrate how to use these new fixtures in both unit and\nintegration tests.\n\n## Utility Fixtures\n\nThe library also comes with some utility fixtures that often come in handy.\nFor example `create_temp_dir`\n(injects the `Path` to a temporary directory into the test using the fixture) and\n`create_temp_cwd` (switches the cwd to a temporary directory and\ninjects its `Path` into the test).\n\n## Project Evolution\n\nThe evolution of this project is being tracked in this [doc](./evolution.md).\n\n## Advantages of `pytest` fixtures\n\n`pytest` fixtures are extremely powerful and flexible.\n\n- Provides a pythonic mechanism for setup, teardown, and injection of state into tests.\n- Fixture scope is configurable allowing for heavy computation to be\n carried out once per test function (default), test module or session.\n- Allows fixtures to be composed which sets up a causal relation between fixtures and\n sharing of state between multiple fixtures and the test function.\n\n## Disadvantages of `pytest` fixtures\n\n### Tunability\n\n`pytest` fixtures lack a straight-forward mechanism for passing arguments to them from\nthe test function defition site.\nIt is not uncommon to require that a specific piece of state be injected before\nrunning a specific test.\nA \"tunable\" fixture would solve this requirement.\n\n`pytest` solves this by *magically* allowing `pytest.mark.parametrize` values to be\npassed through to a fixture being used by a test.\nThis is not obvious and uses a mechanism that is primarily used for\ninjecting multiple states into a test to create multiplicity.\n\n### Importability\n\n`pytest` recommends that fixtures be defined in a `conftest.py` file (a most non-obvious\nname) and that they **not** be imported directly.\nWhen tests are executed `pytest` parses `conftest.py` and magically inserts\nthe fixtures (setup, teardown, and interjection) into the test execution.\nThis is completely different from how the rest of Python operates and\nis a source of great confusion to newcomers.\n\n### Fixtures vs Injected Value\n\n`pytest` fixtures overlap two distinct concepts when connecting a test function to\na fixture.\nOne is the name/handle to the fixture definition (generator function), and\nthe other is the variable inside the test function which is\nbound to the value yielded by the fixture.\n\nThis over-use of a single name is evident every time one is choosing the name for\nthe fixture + variable.\nDoes one name it for the variable or for the operation that the fixture carries out\nwhose side-effect is the value in the varible e.g.\n`add_portfolio` vs `portfolio_name`.\n\n### Type Annotation\n\nThe way `pytest` *registers* fixtures and then *injects/interleaves* them into/with\ntest functions means it is practically impossible for a type engine to match and\nenforce types between the fixture definition and the value injected into\nthe test function.\n\nThis is a source of considerable frustration for anyone who has gone through the\neffort to annotate their code and their tests.\n\n## Prototype\n\nWe provide a prototype for a new type of fixtures beyond what is provided by `pytest`.\n\n### Objectives\n\n- Works seamlessly with `pytest`.\n- Importable from another module (no more `conftest.py`).\n- Composable.\n One fixture can be connected to another fixture and recieve a value from it.\n- Tunable.\n Fixtures definitions can declare parameters.\n These parameters can either be provided at **either**\n the test definition site **or**\n inside the fixture definition module.\n\n The value(s) provided to the parameter(s) will remain consistent throughout\n the execution of any given test.\n The same value will be visible to all participating entities:\n the test function and all fixtures composed with said fixture.\n- Fully typed and type-aware.\n Provides enforceable bindings between fixture definitions,\n values injected into fixtures, and\n values injected from them into test functions.\n\n### Interface\n\nTo achieve **all** of the objectives listed above the interface for these fixtures is\nslightly more verbose than `pytest` fixtures while\nbeing significantly less magical.\n\nThe following four decorators are provided for defining these fixtures:\n\n1. `@fixture`: Applied to a fixture definition (one-shot generator function).\n Creates an instance of the `Fixture` class.\n **This instance is both a decorator as well as a\n reusable and reentrant context manager.**\n\n This instance is applied as a decorator to test functions and injects\n the yielded value into it.\n\n Example (extracted from `tests/unit/utils.py`):\n\n ```python\n @fixture\n def fixture_b(b1: Bi1, b2: Bi2) -> FixtureDefinition[Bo]:\n \"\"\"A fixture that takes injected value from the test function decoration.\"\"\"\n yield Bo(b1=b1, b2=b2)\n ```\n\n *Note* One can use `NewType` and `TypedDict` to constrain the fixture parameters and\n the value it yields which allows for tightly binding the yielded value\n to any location where it is used (test function or composed fixture).\n Similarly the `FixtureDefinition[]` generic type constrains how the fixture is\n allowed to be used.\n\n Each instance has a `.set()` method which is used to provide values for\n any parameters declared in the fixture definition.\n\n `.set()` can be called on either the test function decoration site,\n inside the module defining the fixture,\n or while composing the fixture with another.\n\n Examples (extracted from `tests/unit/utils.py` and\n `tests/unit/test_new_fixtures.py`):\n\n ```python\n @fixture_b.set(Bi1(42), Bi2(3.14))\n def test_b(b: Bo) -> None:\n \"\"\"Test parametrized fixture_b in isolation.\"\"\"\n assert b == {\"b1\": 42, \"b2\": 3.14}\n ```\n\n or\n\n ```python\n @fixture\n @compose(fixture_b.set(Bi1(13), Bi2(1.44)))\n def fixture_c(b: Bo) -> FixtureDefinition[Co]:\n \"\"\"A fixture that takes an injected value from ANOTHER fixture.\"\"\"\n yield Co(c=b)\n ```\n\n All fixture composition and test decoration creates a strict ordering of when the\n fixture's context manager is entered and exited.\n Only the value at the first entry is available throughout the execution of a single\n test.\n\n1. `@compose`: A function that takes a single argument which must be an instance of\n `Fixture` and returns a decorator that is applied to another fixture definition.\n Designed to be applied **before** the fixture definition is wrapped inside\n `@fixture` (don't worry,\n the type system will shout at you if you get the order wrong).\n\n The value yielded by the composed fixture is injected as the first parameter of\n the decorated fixture definition.\n It essentially creates a simpler fixture definition with one less parameter.\n\n Example:\n\n ```python\n @fixture\n @compose(fixture_b.set(Bi1(13), Bi2(1.44)))\n def fixture_c(b: Bo) -> FixtureDefinition[Co]:\n \"\"\"A fixture that takes an injected value from ANOTHER fixture.\"\"\"\n yield Co(c=b)\n ```\n\n The composed fixture can also have its value set from the test site but\n be available to the composition.\n\n Example:\n\n ```python\n @fixture\n @compose(fixture_b)\n def fixture_g(b: Bo, g: Gi) -> FixtureDefinition[Go]:\n \"\"\"Fixture that uses a late-injected fixture_b and a value from the test site.\"\"\"\n yield {\"b\": b, \"g\": g}\n\n @fixture_b.set(Bi1(56), Bi2(9.7))\n @fixture_g.set(Gi(41))\n def test_g(g: Go, b: Bo) -> None:\n \"\"\"Inject args into fixture from test site and trickle down to pulled in fixture.\"\"\"\n assert b == {\"b1\": 56, \"b2\": 9.7}\n assert g == {\"b\": b, \"g\": 41}\n ```\n\n1. `@noinject`: Used at the test definition decoration site to wrap fixtures.\n The wrapped fixture's yielded values will **not** be injected into the test function.\n\n Example:\n\n ```python\n @noinject(fixture_b.set(Bi1(75), Bi2(2.71)))\n def test_b_no_injection() -> None:\n \"\"\"The value yielded by fixture_b is NOT injected into the test.\"\"\"\n ```\n\n The type engine will understand *not* injecting and validates accordingly.\n\n1. `@compose_noinject`: Applied to composed fixtures to *stop* them from injecting\n their yielded value into the fixture they are composed with.\n\n Example:\n\n ```python\n @fixture\n @compose_noinject(fixture_b.set(Bi1(39), Bi2(8.1)))\n def fixture_h(h: Hi) -> FixtureDefinition[Ho]:\n \"\"\"Fixture that uses a composed fixture_b but NOT its yielded value.\"\"\"\n yield Ho(h=h)\n ```\n\n Again, the type engine is aware of the mechanics.\n\n## Implementation\n\nThe implementation can be found in [testing.fixtures](./testing/fixtures).\nIt consists of nested decorators, modified context managers, and parameter injection,\nall fully typed.\n\n## Demo\n\n### Integration Tests\n\nTo demonstrate this in action we have a REST server that:\n\n- receives POST requests\n- fetches data from a (postgres) database\n- uses the fetched data to construct the response\n\nThis has been setup as a composable environment.\nFirst build the local images: `docker-compose build`.\nThen, run the tests: `docker-compose run --rm test`.\n\n### Unit Tests\n\nWe have also provided a number of unit tests, unrelated to the REST server application,\nwhich focus on demonstrating all the possible permutations of fixture usage,\ncomposition, and state injection at both the test and fixture definition site.\n\n## Local Development\n\nTo make changes to this code base the recommendation is to use a virtual env:\n\n```console\npython3.11 -m venv .venv\nsource .venv/bin/activate\npip install \".[dev]\"\n```\n\nYour IDE should be able to now access this virtual env and\nprovide you with autocomplete, intellisense, etc.\n\n## How to Deploy\n\n1. Build the package: `python3.11 -m build`\n This will create the source tarball and wheel in the `dist/` folder.\n\n2. Deploy to pypi: `python3.11 -m twine upload dist/*`\n Enter your pypi username and password.\n",
"bugtrack_url": null,
"license": "",
"summary": "New approach to Python test fixtures (compatible with pytest)",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/abid-mujtaba/testing-fixtures"
},
"split_keywords": [
"fixture",
"fixtures",
"testing",
"tests"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e4108ad5d22fb6b790eaaacf9a8bab43b587b8ea8f6ffd3c3728f63f77668b48",
"md5": "9ca94a131326dc62cb68c573c4e715fe",
"sha256": "f8e6960fde51dc254624702094f258208efea18d59fc2d2842033e9529dad7f6"
},
"downloads": -1,
"filename": "testing_fixtures-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ca94a131326dc62cb68c573c4e715fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9276,
"upload_time": "2024-01-14T19:34:33",
"upload_time_iso_8601": "2024-01-14T19:34:33.728386Z",
"url": "https://files.pythonhosted.org/packages/e4/10/8ad5d22fb6b790eaaacf9a8bab43b587b8ea8f6ffd3c3728f63f77668b48/testing_fixtures-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "32d0e272c216119bf3e1d441a0f0651d2b97a34a9aba05fee7fdd1a5b6a00ca8",
"md5": "073510642361f0af034f7b3880605647",
"sha256": "bdc4d04a5ece0de96431b95a82ae95b3b1b84f3e65ee2c61cfc179d4a88778c5"
},
"downloads": -1,
"filename": "testing_fixtures-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "073510642361f0af034f7b3880605647",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8773,
"upload_time": "2024-01-14T19:34:35",
"upload_time_iso_8601": "2024-01-14T19:34:35.303773Z",
"url": "https://files.pythonhosted.org/packages/32/d0/e272c216119bf3e1d441a0f0651d2b97a34a9aba05fee7fdd1a5b6a00ca8/testing_fixtures-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-14 19:34:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abid-mujtaba",
"github_project": "testing-fixtures",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "testing-fixtures"
}
