datasette.fixtures module, closes #2733

https://gist.github.com/simonw/613be79094d491dd08f45e05f4f70691

Author: simonw

datasette/fixtures.py

@@ -155,9 +155,15 @@ async def all(self):
 functions_marked_as_documented = []
 
 
-def documented(fn):
-    functions_marked_as_documented.append(fn)
-    return fn
+def documented(fn=None, *, label=None):
+    def decorate(fn):
+        fn._datasette_docs_label = label or "internals_utils_{}".format(fn.__name__)
+        functions_marked_as_documented.append(fn)
+        return fn
+
+    if fn is None:
+        return decorate
+    return decorate(fn)
 
 
 @documented

datasette/utils/__init__.py

@@ -13,6 +13,7 @@ Unreleased
 - Fixed a bug where stale tables and other related resources were not removed from ``catalog_*`` tables when a database was removed. (:issue:`2723`)
 - Fixed a Safari bug with the table search mechanism triggered by pressing ``/``. (:issue:`2724`)
 - New "Jump to..." menu item, always visible, for triggering the previously undocumented ``/`` menu. (:issue:`2725`)
+- New documented :ref:`datasette.fixtures.populate_fixture_database(conn) <datasette_fixtures_populate_fixture_database>` helper for creating the fixture database tables used by Datasette's own tests, intended for plugin test suites.
 
 .. _v1_0_a29:
 

docs/changelog.rst

@@ -82,6 +82,48 @@ 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_plugins_datasette_fixtures_database:
+
+Using Datasette's fixtures database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Datasette's own test suite uses a SQLite database with tables that exercise features such as compound primary keys, foreign keys, sortable columns, facets, full-text search and binary data.
+
+You can use those same tables in your plugin tests using the ``populate_fixture_database(conn)`` helper in ``datasette.fixtures``:
+
+Be aware that future Datasette releases may change details of these tables, so try not to rely on their exact structure in your own tests.
+
+.. _datasette_fixtures_populate_fixture_database:
+
+``populate_fixture_database(conn)``
+    Populates an existing SQLite connection with the fixture tables.
+
+For an in-memory test database:
+
+.. code-block:: python
+
+    from datasette.app import Datasette
+    from datasette.fixtures import populate_fixture_database
+    import pytest
+    import pytest_asyncio
+
+
+    @pytest_asyncio.fixture
+    async def datasette():
+        datasette = Datasette()
+        db = datasette.add_memory_database("fixtures")
+        await db.execute_write_fn(populate_fixture_database)
+        await datasette.invoke_startup()
+        return datasette
+
+
+    @pytest.mark.asyncio
+    async def test_facetable(datasette):
+        response = await datasette.client.get(
+            "/fixtures/facetable.json?_shape=array"
+        )
+        assert response.status_code == 200
+
 .. _testing_plugins_autoclose:
 
 Automatic cleanup of Datasette instances

docs/testing_plugins.rst

@@ -72,7 +72,7 @@ async def ds_client():
             "num_sql_threads": 1,
         },
     )
-    from .fixtures import TABLES, TABLE_PARAMETERIZED_SQL
+    from datasette.fixtures import populate_fixture_database
 
     # Use a unique memory_name to avoid collisions between different
     # Datasette instances in the same process, but use "fixtures" for routing
@@ -82,10 +82,7 @@ async def ds_client():
 
     def prepare(conn):
         if not conn.execute("select count(*) from sqlite_master").fetchone()[0]:
-            conn.executescript(TABLES)
-            for sql, params in TABLE_PARAMETERIZED_SQL:
-                with conn:
-                    conn.execute(sql, params)
+            populate_fixture_database(conn)
 
     await db.execute_write_fn(prepare)
     await ds.invoke_startup()
@@ -264,8 +261,6 @@ def ds_unix_domain_socket_server(tmp_path_factory):
     app_client_with_cors,
     app_client_with_dot,
     app_client_with_trace,
-    generate_compound_rows,
-    generate_sortable_rows,
     make_app_client,
     TEMP_PLUGIN_SECRET_FILE,
 )