flake8-assertive 2.2.0
Flake8 unittest assert method checker
License: MIT
Requires Python: >=3.10
Keywords: flake8 testing unittest assert

=================================
Flake8 Unittest Assertion Checker
=================================

|PyPI Version| |Python Versions|

``flake8-assertive`` is a `Flake8 <https://flake8.pycqa.org/>`_ extension that
encourages using richer, more specific `unittest`_ assertions beyond just the
typical ``assertEqual(a, b)`` and ``assertTrue(x)`` methods. The suggested
methods perform more precise checks and provide better failure messages than
the generic methods.

+------------------------------------------+-----------------------------------+------+
| Original                                 | Suggestion                        | Code |
+==========================================+===================================+======+
| ``assertTrue(a == b)``                   | ``assertEqual(a, b)``             | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a != b)``                   | ``assertNotEqual(a, b)``          | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a == b)``                  | ``assertNotEqual(a, b)``          | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a != b)``                  | ``assertEqual(a, b)``             | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a < b)``                    | ``assertLess(a, b)``              | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a <= b)``                   | ``assertLessEqual(a, b)``         | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a > b)``                    | ``assertGreater(a, b)``           | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a >= b)``                   | ``assertGreaterEqual(a, b)``      | A500 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a is b)``                   | ``assertIs(a, b)``                | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a is not b)``               | ``assertIsNot(a, b)``             | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a is b)``                  | ``assertNotIs(a, b)``             | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a is not b)``              | ``assertIs(a, b)``                | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a in b)``                   | ``assertIn(a, b)``                | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a not in b)``               | ``assertNotIn(a, b)``             | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a in b)``                  | ``assertNotIn(a, b)``             | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(isinstance(a, b))``         | ``assertIsInstance(a, b)``        | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(isinstance(a, b))``        | ``assertNotIsInstance(a, b)``     | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertEqual(a, round(b, x))``          | ``assertAlmostEqual(a, b, x)``    | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertAlmostEqual(a, round(b, x))``    | ``assertAlmostEqual(a, b, x)``    | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertNotEqual(a, round(b, x))``       | ``assertNotAlmostEqual(a, b, x)`` | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertNotAlmostEqual(a, round(b, x))`` | ``assertNotAlmostEqual(a, b, x)`` | A501 |
+------------------------------------------+-----------------------------------+------+
| ``assertEqual(a, None)``                 | ``assertIsNone(a)``               | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertNotEqual(a, None)``              | ``assertIsNotNone(a)``            | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a is None)``                | ``assertIsNone(a)``               | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a is not None)``            | ``assertIsNotNone(a)``            | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a is None)``               | ``assertIsNotNone(a)``            | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a is not None)``           | ``assertIsNone(a)``               | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertEqual(a, True)``                 | ``assertTrue(a)``                 | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertEqual(a, False)``                | ``assertFalse(a)``                | A502 |
+------------------------------------------+-----------------------------------+------+
| ``assertEquals(a, b)``                   | ``assertEqual(a, b)``             | A503 |
+------------------------------------------+-----------------------------------+------+
| ``assertNotEquals(a, b)``                | ``assertNotEqual(a, b)``          | A503 |
+------------------------------------------+-----------------------------------+------+
| ``assertAlmostEquals(a, b, x)``          | ``assertAlmostEqual(a, b, x)``    | A503 |
+------------------------------------------+-----------------------------------+------+
| ``assertNotAlmostEquals(a, b, x)``       | ``assertNotAlmostEqual(a, b, x)`` | A503 |
+------------------------------------------+-----------------------------------+------+
| ``assertTrue(a, b)``                     | ``assertTrue(a, msg=b)``          | A504 |
+------------------------------------------+-----------------------------------+------+
| ``assertFalse(a, b)``                    | ``assertFalse(a, msg=b)``         | A504 |
+------------------------------------------+-----------------------------------+------+

Note that some suggestions are normalized forms of the original, such as when
a double-negative is used (``assertFalse(a != b)`` → ``assertEqual(a, b)``).
There aren't suggestions for things like ``assertFalse(a > b)``, which may or
may not be equivalent to ``assertLessEqual(a, b)``.


Installation
------------

Install from PyPI using ``pip``:

.. code-block:: sh

    $ pip install flake8-assertive

The extension will be activated automatically by ``flake8``. You can verify
that it has been loaded by inspecting the ``flake8 --version`` string.

.. code-block:: sh

    $ flake8 --version
    4.0.1 (assertive: 2.1.0, ...) CPython 3.9.10 on Darwin


Error Codes
-----------

This extension adds three new `error codes`__ (using the ``A50`` prefix):

- ``A500``: prefer *{func}* for '*{op}*' comparisons
- ``A501``: prefer *{func}* for '*{op}*' expressions
- ``A502``: prefer *{func}* instead of comparing to *{obj}*
- ``A503``: use *{func}* instead of the deprecated *{name}*
- ``A504``: prefer the 'msg=' kwarg for *{func}* diagnostics

.. __: https://flake8.pycqa.org/en/latest/user/error-codes.html

Configuration
-------------

Configuration values are specified in the ``[flake8]`` section of your `config
file`_ or as command line arguments (e.g. ``--assertive-snakecase``).

- ``assertive-snakecase``: suggest snake_case assert method names
  (e.g. ``assert_true()``) instead of the standard names (e.g. ``assertTrue()``)
- ``assertive-test-pattern``: `fnmatch`_ pattern for identifying unittest test
  files (and all other files will be skipped)

.. _fnmatch: https://docs.python.org/library/fnmatch.html
.. _unittest: https://docs.python.org/library/unittest.html
.. _config file: https://flake8.pycqa.org/en/latest/user/configuration.html

Caveats
-------

There are some specific cases when the suggestion might not match the intent
of the original.

Testing the equality operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``assertEqual()`` won't use the ``==`` operator if the comparison has been
delegated to a `type-specific equalilty function`__. By default, this is the
case for strings, sequences, lists, tuples, sets, and dicts.

.. __: https://docs.python.org/3/library/unittest.html#unittest.TestCase.addTypeEqualityFunc

If your intent is to specifically test the ``==`` operator, consider writing
the assertion like this instead:

.. code-block:: python

    assertIs(a == b, True)

This approach has the benefit of verifying that the type's ``__eq__``
implementation returns a boolean value. Unfortunately, it also has the
downside of reporting the result of ``a == b`` on failure instead of the
values of ``a`` and ``b``.

Suggested by: `Serhiy Storchaka <https://twitter.com/SerhiyStorchaka>`_

Alternatives
------------

- `Teyit <https://github.com/isidentical/teyit>`_ is a Python unit test formatter that
  can perform similar assertion transformations.

.. |PyPI Version| image:: https://img.shields.io/pypi/v/flake8-assertive.svg
   :target: https://pypi.python.org/pypi/flake8-assertive
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/flake8-assertive.svg
   :target: https://pypi.python.org/pypi/flake8-assertive

=======
Changes
=======

2.2.0 (2025-10-11)
------------------

* Drop support for Python 3.7, 3.8, and 3.9. Python 3.10+ is now required.

2.1.0 (2022-03-15)
------------------

* Suggest using an explicit `msg` keyword argument with ``assertTrue()`` and
  ``assertFalse()`` to avoid accidental two-argument misuse. This is controlled
  by a new error code: ``A504``

2.0.0 (2021-12-30)
------------------

* Drop support for Python 2.7 and 3.6, and add 3.10.
* Drop support for flake8 2.x versions.

1.3.0 (2020-10-12)
------------------

* Drop Python version 3.5 support and add version 3.9.

1.2.1 (2019-12-08)
------------------

* Support keyword arguments in assert method calls.

1.2.0 (2019-12-05)
------------------

* Suggest the preferred names for deprecated methods, such as
  ``assertEqual()`` instead of ``assertEquals()``.

1.1.0 (2019-06-26)
------------------

* Suggest ``assertAlmostEqual(a, b, x)`` for ``round()`` expressions like in
  ``assertEqual(a, round(b, x))`` and ``assertAlmostEqual(a, round(b, x))``
  (and similar for ``assertNotEqual()`` and ``assertNotAlmostEqual()``.
* Recognize ``assertAmostEquals()`` and ``assertNotAlmostEquals()`` as aliases
  for ``assertAlmostEqual()`` and ``assertNotAlmostEqual()``.
* Drop Python 3.4 as a supported version since it has been officially retired.

1.0.1 (2018-07-03)
------------------

* Don't make suggestions for assertions containing multiple comparison
  operations (e.g. ``assertTrue(a == b == c)``).

1.0.0 (2018-06-04)
------------------

* Suggest ``assertIsNone(a)`` for ``assertTrue(a is None)``, etc.
* Recognize ``assertEquals()`` and ``assertNotEquals()`` as aliases for
  ``assertEqual()`` and ``assertNotEqual()``.

0.9.0 (2018-05-14)
------------------

* Initial beta release