Add a pytest plugin.

Author: ubernostrum

docs/test_clients.rst

@@ -12,8 +12,8 @@ without needing to build and maintain a set of test mocks to replace the real
 Akismet clients. Both of these clients are configured by subclassing them and
 setting attributes to specify the desired behavior.
 
-For examples of using these test clients, see :ref:`the testing section of the
-usage guide <usage-testing>`.
+For examples of using these test clients, including a pytest plugin for easy
+access to test clients, see :ref:`the testing section of the usage guide <usage-testing>`.
 
 .. autoclass:: TestAsyncClient
 .. autoclass:: TestSyncClient

docs/testing.rst

@@ -31,6 +31,78 @@ subclass:
   :exc:`~akismet.APIKeyError`, allowing you to test your handling of
   that situation.
 
+See :ref:`the test client documentation <test-clients>` for details.
+
+
+Using the pytest plugin
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're using `pytest <https://docs.pytest.org/>`_, ``akismet`` includes a
+pytest plugin which provides the test clients as fixtures:
+
+* ``akismet_async_client``: An instance of the async test client.
+
+* ``akismet_sync_client``: An instance of the sync test client.
+
+* ``akismet_async_class``: The class object for the async test client.
+
+* ``akismet_sync_class``: The class object for the sync test client.
+
+By default, these will succeed at key verification and will mark all content
+as spam. To configure the behavior, you can apply the pytest mark
+``akismet_client``, with arguments ``comment_check_response`` (which should be
+a value from the :class:`~akismet.CheckResponse` enum), and/or
+``verify_key_response`` (which should be a :class:`bool`). For example:
+
+.. tab:: Sync
+
+   .. code-block:: python
+
+      import akismet
+      import pytest
+
+      @pytest.mark.akismet_client(comment_check_response=akismet.CheckResponse.DISCARD)
+      def test_akismet_discard_response(akismet_sync_client: akismet.SyncClient):
+          # Inside this test, akismet_sync_client's comment_check() will always
+          # return CheckResponse.DISCARD.
+
+      @pytest.mark.akismet_client(verify_key_response=False)
+      def test_akismet_fails_key_verification(akismet_sync_class: type[akismet.SyncClient]):
+          # The key verification will always fail on this class.
+          with pytest.raises(akismet.APIKeyError):
+              akismet_sync_class.validated_client()
+
+.. tab:: Async
+
+   .. code-block:: python
+
+      import akismet
+      import pytest
+
+      @pytest.mark.akismet_client(comment_check_response=akismet.CheckResponse.DISCARD)
+      async def test_akismet_discard_response(akismet_async_client: akismet.ASyncClient):
+          # Inside this test, akismet_async_client's comment_check() will always
+          # return CheckResponse.DISCARD.
+
+      @pytest.mark.akismet_client(verify_key_response=False)
+      async def test_akismet_fails_key_verification(akismet_async_class: type[akismet.ASyncClient]):
+          # Key verification will always fail on this class and on all instances
+          # of it.
+          with pytest.raises(akismet.APIKeyError):
+              await akismet_async_class.validated_client()
+
+As a general guideline, request the client class fixtures when you want to test
+key verification handling in your own code, or when you're using some testing
+pattern which will construct instances on demand from the class, and otherwise
+always request a client instance fixture.
+
+Testing with ``unittest``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you use the Python standard library's ``unittest`` module, or another test
+setup derived from it (such as Django's testing tools), you can create and use
+test client classes directly in your tests.
+
 For example:
 
 .. tab:: Sync
@@ -127,6 +199,9 @@ For example:
          verify_key_response = False
 
 
+Testing against the live Akismet service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 If you also want to perform live end-to-end testing of your use of Akismet, you
 can do so with a real Akismet API client, by passing the optional keyword
 argument ``is_test=1`` to the comment-check, submit-ham, and submit-spam
@@ -142,7 +217,7 @@ certain special values for use in triggering specific responses:
   always cause Akismet to mark the content as not spam.
 
 However, it is generally discouraged to make live requests to an external
-service as part of a normal test suite -- for most cases you should be making
+service as part of a normal test suite, For most cases you should be making
 use of the included test clients.
 
 
@@ -234,14 +309,14 @@ responses without needing to contact the live Akismet web service, so setting
 the environment variables for your Akismet API key and site URL is not
 necessary to run the normal test suite.
 
-However, there is a separate test file -- found at ``tests/end_to_end.py`` --
-which is not run as part of the usual test suite invoked by ``nox`` and which
-makes live requests to Akismet. Running the tests in that file *does* require
-setting the ``PYTHON_AKISMET_API_KEY`` and ``PYTHON_AKISMET_BLOG_URL``
-environment variables to valid values, after which you can run the end-to-end
-tests by invoking ``nox`` and asking it to run tasks with the keyword
-``release`` (normally this test file is only run as a final check prior to
-issuing a new release, hence the keyword name):
+However, there is a separate test file--found at ``tests/end_to_end.py``--which
+is not run as part of the usual test suite invoked by ``nox`` and which makes
+live requests to Akismet. Running the tests in that file *does* require setting
+the ``PYTHON_AKISMET_API_KEY`` and ``PYTHON_AKISMET_BLOG_URL`` environment
+variables to valid values, after which you can run the end-to-end tests by
+invoking ``nox`` and asking it to run tasks with the keyword ``release``
+(normally this test file is only run as a final check prior to issuing a new
+release, hence the keyword name):
 
 .. tab:: macOS/Linux/other Unix
 

docs/usage.rst

@@ -423,67 +423,38 @@ And then test it like so:
       from your_app.moderation import flag_spam_comment
 
 
-      class AlwaysSpam(akismet.TestSyncClient):
-          """
-          An Akismet client whose comment_check() always returns SPAM.
-
-          """
-          comment_check_response = akismet.CheckResponse.SPAM
-
-
-      class NeverSpam(akismet.TestSyncClient):
-          """
-          An Akismet client whose comment_check() always returns HAM.
-
-          """
-          comment_check_response = akismet.CheckResponse.HAM
-
-
-      @pytest.fixture
-      def always_spam_client():
-          """
-          pytest fixture yielding an AlwaysSpam client instance.
-
-          """
-          with AlwaysSpam() as akismet_client:
-              yield akismet_client
-
-
-      @pytest.fixture
-      def never_spam_client():
-          """
-          pytest fixture yielding a NeverSpam client instance.
-
-          """
-          with NeverSpam() as akismet_client:
-              yield akismet_client
-
-
       # The following test functions assume you have also defined pytest
       # fixtures to create the request and comment objects.
-
-      def test_flag_set_on_spam(always_spam_client, test_request, test_comment):
+      #
+      #
+      # A pytest plugin provided with akismet defines fixtures for
+      # sync and async clients, with behavior configured by the
+      # akismet_client mark.
+
+      @pytest.mark.akismet_client(comment_check_response=akismet.CheckResponse.SPAM)
+      def test_flag_set_on_spam(akismet_sync_client, test_request, test_comment):
           """
           When the comment is identified as spam, the "filtered" attribute
           is set to True.
 
           """
           comment = flag_spam_comment(
-              always_spam_client,
+              akismet_sync_client,
               test_request,
               test_comment
           )
           assert comment.filtered
 
 
-      def test_flag_not_set_on_non_spam(never_spam_client, test_request, test_comment):
+      @pytest.mark.akismet_client(comment_check_response=akismet.CheckResponse.HAM)
+      def test_flag_not_set_on_non_spam(akismet_sync_client, test_request, test_comment):
           """
           When the comment is identified as non-spam, the "filtered" attribute
           is set to False.
 
           """
           comment = flag_spam_comment(
-              never_spam_client,
+              akismet_sync_client,
               test_request,
               test_comment
           )

pyproject.toml

@@ -35,7 +35,7 @@ keywords = ["akismet", "spam", "spam-filtering"]
 license = { text = "BSD-3-Clause" }
 readme = "README.rst"
 requires-python = ">=3.9"
-version = "24.11.1a0"
+version = "25.10.1a0"
 
 [dependency-groups]
 tests = [
@@ -44,6 +44,9 @@ tests = [
     "pytest",
 ]
 
+[project.entry-points.pytest11]
+akismet = "akismet.pytest_plugin"
+
 [project.urls]
 "Documentation" = "https://akismet.readthedocs.io"
 "Source Code" = "https://github.com/ubernostrum/akismet"