From 7506a89be0d1c97632bed47635eb90f92815d6c7 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Wed, 10 Jan 2024 13:04:34 -0800
Subject: [PATCH] Docs on datasette.client for tests, closes #1830

Also covers ds.client.actor_cookie() helper
---
 docs/testing_plugins.rst | 28 +++++++++++++++++++++++++++
 tests/test_docs.py       | 41 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/docs/testing_plugins.rst b/docs/testing_plugins.rst
index 6d2097ad08..e10514c6c5 100644
--- a/docs/testing_plugins.rst
+++ b/docs/testing_plugins.rst
@@ -82,6 +82,34 @@ This method registers any :ref:`plugin_hook_startup` or :ref:`plugin_hook_prepar
 
 If you are using ``await datasette.client.get()`` and similar methods then you don't need to worry about this - Datasette automatically calls ``invoke_startup()`` the first time it handles a request.
 
+.. _testing_datasette_client:
+
+Using datasette.client in tests
+-------------------------------
+
+The :ref:`internals_datasette_client` mechanism is designed for use in tests. It provides access to a pre-configured `HTTPX async client <https://www.python-httpx.org/async/>`__ instance that can make GET, POST and other HTTP requests against a Datasette instance from inside a test.
+
+I simple test looks like this:
+
+.. literalinclude:: ../tests/test_docs.py
+   :language: python
+   :start-after: # -- start test_homepage --
+   :end-before: # -- end test_homepage --
+
+Or for a JSON API:
+
+.. literalinclude:: ../tests/test_docs.py
+   :language: python
+   :start-after: # -- start test_actor_is_null --
+   :end-before: # -- end test_actor_is_null --
+
+To make requests as an authenticated actor, create a signed ``ds_cookie`` using the ``datasette.client.actor_cookie()`` helper function and pass it in ``cookies=`` like this:
+
+.. literalinclude:: ../tests/test_docs.py
+   :language: python
+   :start-after: # -- start test_signed_cookie_actor --
+   :end-before: # -- end test_signed_cookie_actor --
+
 .. _testing_plugins_pdb:
 
 Using pdb for errors thrown inside Datasette
diff --git a/tests/test_docs.py b/tests/test_docs.py
index e9b813feda..fdd4478825 100644
--- a/tests/test_docs.py
+++ b/tests/test_docs.py
@@ -1,9 +1,8 @@
 """
 Tests to ensure certain things are documented.
 """
-from click.testing import CliRunner
 from datasette import app, utils
-from datasette.cli import cli
+from datasette.app import Datasette
 from datasette.filters import Filters
 from pathlib import Path
 import pytest
@@ -102,3 +101,41 @@ def documented_fns():
 @pytest.mark.parametrize("fn", utils.functions_marked_as_documented)
 def test_functions_marked_with_documented_are_documented(documented_fns, fn):
     assert fn.__name__ in documented_fns
+
+
+# Tests for testing_plugins.rst documentation
+
+
+# -- start test_homepage --
+@pytest.mark.asyncio
+async def test_homepage():
+    ds = Datasette(memory=True)
+    response = await ds.client.get("/")
+    html = response.text
+    assert "<h1>" in html
+
+
+# -- end test_homepage --
+
+
+# -- start test_actor_is_null --
+@pytest.mark.asyncio
+async def test_actor_is_null():
+    ds = Datasette(memory=True)
+    response = await ds.client.get("/-/actor.json")
+    assert response.json() == {"actor": None}
+
+
+# -- end test_actor_is_null --
+
+
+# -- start test_signed_cookie_actor --
+@pytest.mark.asyncio
+async def test_signed_cookie_actor():
+    ds = Datasette(memory=True)
+    cookies = {"ds_actor": ds.client.actor_cookie({"id": "root"})}
+    response = await ds.client.get("/-/actor.json", cookies=cookies)
+    assert response.json() == {"actor": {"id": "root"}}
+
+
+# -- end test_signed_cookie_actor --