From e7972624f5d4e4012c967a7619874bac1f14c523 Mon Sep 17 00:00:00 2001 From: Brian Okken <1568356+okken@users.noreply.github.com> Date: Thu, 18 Jan 2024 12:16:52 -0800 Subject: [PATCH] doc update --- README.md | 81 +++++++++++++++++-------- changelog.md | 7 +++ examples/test_example_fail_func.py | 2 +- examples/test_example_fail_in_thread.py | 2 +- examples/test_example_pass_in_thread.py | 2 +- pyproject.toml | 2 +- 6 files changed, 68 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 4df4f0c..f78d4bb 100644 --- a/README.md +++ b/README.md @@ -65,28 +65,33 @@ def test_httpx_get(check): `check` also helper functions for common checks. These methods do NOT need to be inside of a `with check:` block. -- **check.equal** - *a == b* -- **check.not_equal** - *a != b* -- **check.is_** - *a is b* -- **check.is_not** - *a is not b* -- **check.is_true** - *bool(x) is True* -- **check.is_false** - *bool(x) is False* -- **check.is_none** - *x is None* -- **check.is_not_none** - *x is not None* -- **check.is_in** - *a in b* -- **check.is_not_in** - *a not in b* -- **check.is_instance** - *isinstance(a, b)* -- **check.is_not_instance** - *not isinstance(a, b)* -- **check.almost_equal** - *a == pytest.approx(b, rel, abs)* see at: [pytest.approx](https://docs.pytest.org/en/latest/reference.html#pytest-approx) -- **check.not_almost_equal** - *a != pytest.approx(b, rel, abs)* see at: [pytest.approx](https://docs.pytest.org/en/latest/reference.html#pytest-approx) -- **check.greater** - *a > b* -- **check.greater_equal** - *a >= b* -- **check.less** - *a < b* -- **check.less_equal** - *a <= b* -- **check.between(b, a, c, ge=False, le=False)** - *a < b < c* -- **check.between_equal(b, a, c)** - *a <= b <= c* -- **check.raises** - *func raises given exception* similar to [pytest.raises](https://docs.pytest.org/en/latest/reference/reference.html#pytest-raises) -- **check.fail(msg)** - *Log a failure* +| Function | Meaning | Notes | +|------------------------------------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------| +| `equal(a, b, msg="")` | `a == b` | | +| `not_equal(a, b, msg="")` | `a != b` | | +| `is_(a, b, msg="")` | `a is b` | | +| `is_not(a, b, msg="")` | `a is not b` | | +| `is_true(x, msg="")` | `bool(x) is True` | | +| `is_false(x, msg="")` | `bool(x) is False` | | +| `is_none(x, msg="")` | `x is None` | | +| `is_not_none(x, msg="")` | `x is not None` | | +| `is_in(a, b, msg="")` | `a in b` | | +| `is_not_in(a, b, msg="")` | `a not in b` | | +| `is_instance(a, b, msg="")` | `isinstance(a, b)` | | +| `is_not_instance(a, b, msg="")` | `not isinstance(a, b)` | | +| `almost_equal(a, b, rel=None, abs=None, msg="")` | `a == pytest.approx(b, rel, abs)` | [pytest.approx](https://docs.pytest.org/en/latest/reference.html#pytest-approx) | +| `not_almost_equal(a, b, rel=None, abs=None, msg="")` | `a != pytest.approx(b, rel, abs)` | [pytest.approx](https://docs.pytest.org/en/latest/reference.html#pytest-approx) | +| `greater(a, b, msg="")` | `a > b` | | +| `greater_equal(a, b, msg="")` | `a >= b` | | +| `less(a, b, msg="")` | `a < b` | | +| `less_equal(a, b, msg="")` | `a <= b` | | +| `between(b, a, c, msg="", ge=False, le=False)` | `a < b < c` | | +| `between_equal(b, a, c, msg="")` | `a <= b <= c` | same as `between(b, a, c, msg, ge=True, le=True)` | +| `raises(expected_exception, *args, **kwargs)` | *Raises given exception* | similar to [pytest.raises](https://docs.pytest.org/en/latest/reference/reference.html#pytest-raises) | +| `fail(msg)` | *Log a failure* | | + +**Note: This is a list of relatively common logic operators. I'm reluctant to add to the list too much, as it's easy to add your own.** + The httpx example can be rewritten with helper functions: @@ -103,8 +108,9 @@ Which you use is personal preference. ## Defining your own check functions -The `@check.check_func` decorator allows you to wrap any test helper that has an assert -statement in it to be a non-blocking assert function. +### Using `@check.check_func` + +The `@check.check_func` decorator allows you to wrap any test helper that has an assert statement in it to be a non-blocking assert function. ```python @@ -121,6 +127,33 @@ def test_all_four(): is_four(4) ``` + +### Using `check.fail()` + +Using `@check.check_func` is probably the easiest. +However, it does have a bit of overhead in the passing cases +that can affect large loops of checks. + +If you need a bit of a speedup, use the following style with the help of `check.fail()`. + +```python +from pytest_check import check + +def is_four(a): + __tracebackhide__ = True + if a == 4: + return True + else: + check.fail(f"check {a} == 4") + return False + +def test_all_four(): + is_four(1) + is_four(2) + is_four(3) + is_four(4) +``` + ## Using raises as a context manager `raises` is used as context manager, much like `pytest.raises`. The main difference being that a failure to raise the right exception won't stop the execution of the test method. diff --git a/changelog.md b/changelog.md index 4c88905..7980911 100644 --- a/changelog.md +++ b/changelog.md @@ -20,6 +20,13 @@ All notable changes to this project be documented in this file. --> +## [2.3.1] - 2024-Jan-18 + +### Modified +- Documentation Update, README.md + - Turn help function list into a table with param lists + - Show an alternative method of creating a helper function using `check.fail()` + ## [2.3.0] - 2024-Jan-17 ### Added diff --git a/examples/test_example_fail_func.py b/examples/test_example_fail_func.py index 3976a6c..86bbc25 100644 --- a/examples/test_example_fail_func.py +++ b/examples/test_example_fail_func.py @@ -1,4 +1,4 @@ -import pytest_check as check +from pytest_check import check def test_one_failure(): diff --git a/examples/test_example_fail_in_thread.py b/examples/test_example_fail_in_thread.py index b67487b..05dae52 100644 --- a/examples/test_example_fail_in_thread.py +++ b/examples/test_example_fail_in_thread.py @@ -2,7 +2,7 @@ from threading import Thread -import pytest_check as check +from pytest_check import check def force_fail(comparison): diff --git a/examples/test_example_pass_in_thread.py b/examples/test_example_pass_in_thread.py index 8936317..b0a4d9f 100644 --- a/examples/test_example_pass_in_thread.py +++ b/examples/test_example_pass_in_thread.py @@ -2,7 +2,7 @@ from threading import Thread -import pytest_check as check +from pytest_check import check def always_pass(): diff --git a/pyproject.toml b/pyproject.toml index 59412d8..0bbb251 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ authors = [{name = "Brian Okken"}] readme = "README.md" license = {file = "LICENSE.txt"} description="A pytest plugin that allows multiple failures per test." -version = "2.3.0" +version = "2.3.1" requires-python = ">=3.7" classifiers = [ "License :: OSI Approved :: MIT License",