about summary refs log tree commit diff
path: root/test/python
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-10-08 11:24:58 +0000
committerPjotr <wrk@bosa.lan>2026-10-08 11:55:30 +0000
commit22540223c43342473d7d428dffeeab9d94afb55c (patch)
treef81c6af04ea9157054a58d3fc20e99f55973a0ae /test/python
parent5650076cdf45a26aed8c6166069d74281a7f4bd7 (diff)
downloadgenenetwork4-22540223c43342473d7d428dffeeab9d94afb55c.tar.gz
* src/response.rs: wrap every success response in one envelope.
Breaking: every success body is now {"data", "meta": {"state",
"took_ms", "request_id"}, "notes", "next"}; clients read `data`. Only
`/` (plain text) and `/openapi.json` are unwrapped.

* src/response.rs (Envelope, Meta, State, Ctx, RequestInfo): handlers
take Ctx first and build the response with ctx.envelope(data), so
timing and the request id are never filled in by hand. `state` is
`complete` or `partial`; notes are server-authored only; `next` are
concrete relative hrefs (path_segment percent-encodes names).
* src/routes/*.rs, src/lib.rs (version): every handler returns
Envelope<..> with next links; /search is `partial` when the locus
lookup fails or a sorted 1000-hit window may be truncated, and
/publications/{pubmed_id}/traits when datasets were left out for
authorization.
* src/error.rs (ApiError): add `took_ms`, an RFC 7807 extension member.
* src/auth.rs (AuthToken): the 401 now carries request_id and took_ms
(it never had a request_id); Ctx stores RequestInfo in the request
extensions for it.

* tests: common::data / envelope_data parse every success body through
the envelope; tests/envelope.rs and test/python/test_envelope.py check
the shape, errors, and that every `next` link resolves;
tests/envelope_partial.rs checks the `partial` search without a
database; tests/openapi.rs fails if a JSON success response is not an
Envelope_* schema.
* README.md, docs/SKILL.md, docs/gn-auth.md, RELEASE_NOTES.md: document
the envelope and took_ms on errors.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Diffstat (limited to 'test/python')
-rw-r--r--test/python/auth_helpers.py2
-rw-r--r--test/python/server_test_case.py13
-rw-r--r--test/python/test_dataset_by_name.py4
-rw-r--r--test/python/test_dataset_probeset_info.py4
-rw-r--r--test/python/test_dataset_probeset_values.py4
-rw-r--r--test/python/test_dataset_probesets.py4
-rw-r--r--test/python/test_envelope.py135
-rw-r--r--test/python/test_get_test_token.py4
-rw-r--r--test/python/test_group_by_name.py6
-rw-r--r--test/python/test_group_case_attributes.py6
-rw-r--r--test/python/test_group_datasets.py4
-rw-r--r--test/python/test_group_strains.py6
-rw-r--r--test/python/test_group_trait_info.py6
-rw-r--r--test/python/test_group_trait_values.py4
-rw-r--r--test/python/test_group_traits.py8
-rw-r--r--test/python/test_groups.py6
-rw-r--r--test/python/test_publications.py4
-rw-r--r--test/python/test_search.py50
-rw-r--r--test/python/test_species.py4
-rw-r--r--test/python/test_species_by_name.py4
-rw-r--r--test/python/test_species_datasets.py4
-rw-r--r--test/python/test_traits.py16
-rw-r--r--test/python/test_version.py4
23 files changed, 248 insertions, 54 deletions
diff --git a/test/python/auth_helpers.py b/test/python/auth_helpers.py
index 8b3e80d..091c823 100644
--- a/test/python/auth_helpers.py
+++ b/test/python/auth_helpers.py
@@ -50,7 +50,7 @@ def auth_token():
         conn.request("POST", "/get-test-token")
         response = conn.getresponse()
         if response.status == 200:
-            return json.loads(response.read())["access_token"]
+            return json.loads(response.read())["data"]["access_token"]
     except OSError:
         pass
     finally:
diff --git a/test/python/server_test_case.py b/test/python/server_test_case.py
index be2dcf9..c400661 100644
--- a/test/python/server_test_case.py
+++ b/test/python/server_test_case.py
@@ -4,6 +4,7 @@ integration tests under tests/, which call the router in-process).
 """
 
 import hashlib
+import json
 import os
 import socket
 import struct
@@ -17,6 +18,18 @@ HOST = "127.0.0.1"
 PORT = os.environ.get("GENENETWORK4_PORT", "3000")
 
 
+def envelope_data(body):
+    """The `data` of a success response body, after checking that the
+    body is the standard envelope: `meta` (state, took_ms, request_id),
+    `notes` and `next` next to `data`."""
+    envelope = json.loads(body)
+    assert isinstance(envelope["meta"]["state"], str), envelope
+    assert isinstance(envelope["meta"]["took_ms"], int), envelope
+    assert isinstance(envelope["notes"], list), envelope
+    assert isinstance(envelope["next"], list), envelope
+    return envelope["data"]
+
+
 def wait_for_port(host, port, timeout=10):
     deadline = time.time() + timeout
     while time.time() < deadline:
diff --git a/test/python/test_dataset_by_name.py b/test/python/test_dataset_by_name.py
index 51c1879..58414a8 100644
--- a/test/python/test_dataset_by_name.py
+++ b/test/python/test_dataset_by_name.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -43,7 +43,7 @@ class DatasetByNameTest(ServerTestCase):
         response, body = self.get("/datasets/Br_U_0803_M")
         self.assertEqual(response.status, 200)
 
-        dataset = json.loads(body)
+        dataset = envelope_data(body)
         self.assertEqual(dataset["name"], "Br_U_0803_M")
         self.assertEqual(dataset["full_name"], "Brain U74Av2 08/03 MAS5")
         self.assertEqual(dataset["data_scale"], "log2")
diff --git a/test/python/test_dataset_probeset_info.py b/test/python/test_dataset_probeset_info.py
index 861e9ca..a5c232d 100644
--- a/test/python/test_dataset_probeset_info.py
+++ b/test/python/test_dataset_probeset_info.py
@@ -14,7 +14,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_server_reachable, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -52,7 +52,7 @@ class DatasetProbesetInfoTest(ServerTestCase):
         response, body = self.get("/datasets/Br_U_0803_M/probesets/100001_at")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["name"], "100001_at")
         self.assertEqual(info["symbol"], "Cd3g")
         self.assertIsInstance(info["mean"], float)
diff --git a/test/python/test_dataset_probeset_values.py b/test/python/test_dataset_probeset_values.py
index b11b5d6..d4fcd03 100644
--- a/test/python/test_dataset_probeset_values.py
+++ b/test/python/test_dataset_probeset_values.py
@@ -14,7 +14,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_server_reachable, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -52,7 +52,7 @@ class DatasetProbesetValuesTest(ServerTestCase):
         response, body = self.get("/datasets/Br_U_0803_M/probesets/100001_at/values")
         self.assertEqual(response.status, 200)
 
-        values = json.loads(body)
+        values = envelope_data(body)
         self.assertTrue(values)
         bxd1 = next(v for v in values if v["name"] == "BXD1")
         self.assertIsInstance(bxd1["value"], float)
diff --git a/test/python/test_dataset_probesets.py b/test/python/test_dataset_probesets.py
index c12b42a..66c6361 100644
--- a/test/python/test_dataset_probesets.py
+++ b/test/python/test_dataset_probesets.py
@@ -13,7 +13,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_server_reachable, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -51,7 +51,7 @@ class DatasetProbesetsTest(ServerTestCase):
         response, body = self.get("/datasets/Br_U_0803_M/probesets")
         self.assertEqual(response.status, 200)
 
-        probesets = json.loads(body)
+        probesets = envelope_data(body)
         self.assertTrue(probesets)
         names = {record["name"] for record in probesets}
         self.assertIn("100001_at", names)
diff --git a/test/python/test_envelope.py b/test/python/test_envelope.py
new file mode 100644
index 0000000..160a50c
--- /dev/null
+++ b/test/python/test_envelope.py
@@ -0,0 +1,135 @@
+"""Mirrors tests/envelope.rs and the envelope check of tests/openapi.rs:
+the success envelope (`data` next to `meta`, `notes` and `next`) on
+every endpoint except `/` and `/openapi.json`, and that every `next`
+href resolves. The `/version` and OpenAPI checks need nothing else; the
+`next` crawl needs a live MariaDB and a token (see docs/gn-auth.md) and
+skips with a message when either is missing.
+"""
+
+import http.client
+import json
+import unittest
+
+from auth_helpers import TOKEN_ENV, auth_token
+from server_test_case import HOST, PORT, ServerTestCase, database_reachable
+
+# Hrefs not followed: lists of thousands of rows (every trait of a
+# group, every probeset of a dataset).
+TOO_LARGE_SUFFIXES = ("/traits", "/probesets")
+
+SEEDS = [
+    "/species",
+    "/species/mouse",
+    "/species/mouse/datasets",
+    "/groups",
+    "/groups/BXD",
+    "/groups/BXD/strains",
+    "/groups/BXD/case-attributes",
+    "/groups/BXD/datasets",
+    "/groups/BXD/traits?abbreviation=5HT_MB_M",
+    "/groups/BXD/traits/17985",
+    "/groups/BXD/traits/17985/values",
+    "/datasets/Br_U_0803_M",
+    "/datasets/Br_U_0803_M/probesets/100001_at",
+    "/datasets/Br_U_0803_M/probesets/100001_at/values",
+    "/traits/BXDPublish/17985",
+    "/traits/BXDPublish/17985/values",
+    "/publications/24102824/traits",
+]
+
+
+class EnvelopeTest(ServerTestCase):
+    EXTRA_ENV = TOKEN_ENV
+
+    def get(self, path, token=None, timeout=60):
+        conn = http.client.HTTPConnection(HOST, int(PORT), timeout=timeout)
+        try:
+            headers = {"Authorization": f"Bearer {token}"} if token else {}
+            conn.request("GET", path, headers=headers)
+            response = conn.getresponse()
+            return response, response.read()
+        finally:
+            conn.close()
+
+    def test_version_is_wrapped_in_the_envelope(self):
+        response, body = self.get("/version")
+        self.assertEqual(response.status, 200)
+        envelope = json.loads(body)
+        self.assertEqual(envelope["data"]["name"], "GeneNetwork4")
+        self.assertEqual(envelope["meta"]["state"], "complete")
+        self.assertIsInstance(envelope["meta"]["took_ms"], int)
+        self.assertEqual(
+            envelope["meta"]["request_id"], response.getheader("x-request-id")
+        )
+        self.assertEqual(envelope["notes"], [])
+        self.assertEqual(envelope["next"], [])
+
+    def test_errors_carry_the_request_id_and_took_ms(self):
+        # The token extractor's 401: needs no database or gn-auth.
+        response, body = self.get("/species")
+        self.assertEqual(response.status, 401)
+        error = json.loads(body)
+        self.assertEqual(error["code"], "invalid_token")
+        self.assertEqual(error["request_id"], response.getheader("x-request-id"))
+        self.assertIsInstance(error["took_ms"], int)
+
+    def test_the_greeting_and_the_openapi_document_are_not_wrapped(self):
+        response, body = self.get("/")
+        self.assertEqual(response.status, 200)
+        self.assertEqual(body, b"Hello, world!")
+
+        response, body = self.get("/openapi.json")
+        doc = json.loads(body)
+        self.assertIn("openapi", doc)
+        self.assertNotIn("meta", doc)
+
+    def test_every_json_success_response_is_an_envelope(self):
+        _, body = self.get("/openapi.json")
+        checked = 0
+        for path, item in json.loads(body)["paths"].items():
+            for method, operation in item.items():
+                content = operation["responses"].get("200", {}).get("content", {})
+                body_schema = content.get("application/json")
+                if body_schema is None:
+                    continue
+                schema = body_schema["schema"].get("$ref", "")
+                self.assertTrue(
+                    schema.startswith("#/components/schemas/Envelope_"),
+                    f"{method} {path}: 200 response is {schema!r}, not an envelope",
+                )
+                checked += 1
+        self.assertGreaterEqual(checked, 20)
+
+    def test_next_links_resolve(self):
+        if not database_reachable():
+            self.skipTest("no database on 127.0.0.1:3306")
+        token = auth_token()
+        if not token:
+            self.skipTest("no token (see docs/gn-auth.md)")
+
+        followed = 0
+        for seed in SEEDS:
+            response, body = self.get(seed, token)
+            self.assertEqual(response.status, 200, f"GET {seed}: {body[:200]}")
+            envelope = json.loads(body)
+            self.assertEqual(
+                envelope["meta"]["request_id"], response.getheader("x-request-id"), seed
+            )
+            self.assertIsInstance(envelope["meta"]["took_ms"], int, seed)
+            for nxt in envelope["next"]:
+                href = nxt["href"]
+                self.assertTrue(href.startswith("/"), f"{seed}: relative href {href}")
+                self.assertIsInstance(nxt["description"], str)
+                if href.endswith(TOO_LARGE_SUFFIXES):
+                    continue
+                response, linked = self.get(href, token)
+                self.assertEqual(
+                    response.status, 200, f"{seed} suggests {href}: {linked[:200]}"
+                )
+                self.assertIn("state", json.loads(linked)["meta"])
+                followed += 1
+        self.assertGreaterEqual(followed, 20)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/python/test_get_test_token.py b/test/python/test_get_test_token.py
index 2426ebd..6cd07c0 100644
--- a/test/python/test_get_test_token.py
+++ b/test/python/test_get_test_token.py
@@ -13,7 +13,7 @@ import os
 import unittest
 from urllib.parse import urlparse
 
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 AUTH_SERVER_URL = os.environ.get("AUTH_SERVER_URL", "http://127.0.0.1:8081/")
 
@@ -82,7 +82,7 @@ class GetTestTokenEnabledTest(ServerTestCase):
         response, body = post_test_token()
         self.assertEqual(response.status, 200)
 
-        token = json.loads(body)
+        token = envelope_data(body)
         self.assertTrue(token["access_token"])
         self.assertEqual(token["token_type"], "Bearer")
 
diff --git a/test/python/test_group_by_name.py b/test/python/test_group_by_name.py
index a753e91..f562cbe 100644
--- a/test/python/test_group_by_name.py
+++ b/test/python/test_group_by_name.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import database_reachable, HOST, PORT, ServerTestCase
+from server_test_case import database_reachable, HOST, PORT, ServerTestCase, envelope_data
 
 
 
@@ -35,7 +35,7 @@ class GroupByNameTest(ServerTestCase):
         response, body = self.get("/groups/BXD")
         self.assertEqual(response.status, 200)
 
-        group = json.loads(body)
+        group = envelope_data(body)
         self.assertEqual(group["name"], "BXD")
         self.assertEqual(group["display_name"], "BXD")
         self.assertEqual(group["genetic_type"], "riset")
@@ -50,7 +50,7 @@ class GroupByNameTest(ServerTestCase):
         response, body = self.get("/groups/1")
         self.assertEqual(response.status, 200)
 
-        group = json.loads(body)
+        group = envelope_data(body)
         self.assertEqual(group["name"], "BXD")
         self.assertEqual(group["id"], 1)
 
diff --git a/test/python/test_group_case_attributes.py b/test/python/test_group_case_attributes.py
index 71c933f..30c717c 100644
--- a/test/python/test_group_case_attributes.py
+++ b/test/python/test_group_case_attributes.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -49,7 +49,7 @@ class GroupCaseAttributesTest(ServerTestCase):
         response, body = self.get("/groups/BXD/case-attributes")
         self.assertEqual(response.status, 200)
 
-        case_attributes = json.loads(body)
+        case_attributes = envelope_data(body)
         self.assertEqual(
             case_attributes["names"], ["Epoch", "RRID", "SeqCvge", "Status"]
         )
@@ -71,7 +71,7 @@ class GroupCaseAttributesTest(ServerTestCase):
         response, body = self.get("/groups/LXS/case-attributes")
         self.assertEqual(response.status, 200)
 
-        case_attributes = json.loads(body)
+        case_attributes = envelope_data(body)
         self.assertEqual(case_attributes["names"], [])
         self.assertEqual(case_attributes["values"], [])
 
diff --git a/test/python/test_group_datasets.py b/test/python/test_group_datasets.py
index f386d2c..c35b819 100644
--- a/test/python/test_group_datasets.py
+++ b/test/python/test_group_datasets.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -43,7 +43,7 @@ class GroupDatasetsTest(ServerTestCase):
         response, body = self.get("/groups/BXD/datasets")
         self.assertEqual(response.status, 200)
 
-        datasets = json.loads(body)
+        datasets = envelope_data(body)
         self.assertTrue(datasets)
         names = {record["name"] for record in datasets}
         self.assertIn("Br_U_0803_M", names)
diff --git a/test/python/test_group_strains.py b/test/python/test_group_strains.py
index ccb8faa..c2b2e19 100644
--- a/test/python/test_group_strains.py
+++ b/test/python/test_group_strains.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import database_reachable, HOST, PORT, ServerTestCase
+from server_test_case import database_reachable, HOST, PORT, ServerTestCase, envelope_data
 
 
 
@@ -35,7 +35,7 @@ class GroupStrainsTest(ServerTestCase):
         response, body = self.get("/groups/BXD/strains")
         self.assertEqual(response.status, 200)
 
-        strains = json.loads(body)
+        strains = envelope_data(body)
         self.assertTrue(strains)
         bxd1 = next(s for s in strains if s["name"] == "BXD1")
         self.assertTrue(bxd1["used_for_mapping"])
@@ -47,7 +47,7 @@ class GroupStrainsTest(ServerTestCase):
         response, body = self.get("/groups/BXD/strains?used_for_mapping=true")
         self.assertEqual(response.status, 200)
 
-        strains = json.loads(body)
+        strains = envelope_data(body)
         self.assertTrue(strains)
         self.assertTrue(all(s["used_for_mapping"] for s in strains))
         names = {s["name"] for s in strains}
diff --git a/test/python/test_group_trait_info.py b/test/python/test_group_trait_info.py
index 7375524..75f1889 100644
--- a/test/python/test_group_trait_info.py
+++ b/test/python/test_group_trait_info.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -45,7 +45,7 @@ class GroupTraitInfoTest(ServerTestCase):
         response, body = self.get("/groups/BXD/traits/17985")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["locus"], "rsm10000012461")
         self.assertEqual(info["abbreviation"], "5HT_MB_M")
         self.assertEqual(info["dataset"], "BXDPublish")
@@ -64,7 +64,7 @@ class GroupTraitInfoTest(ServerTestCase):
         response, body = self.get("/groups/BXD/traits/10001")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["id"], 10001)
         self.assertEqual(info["units"], "mg")
         self.assertIn("Cerebellum weight", info["post_publication_description"])
diff --git a/test/python/test_group_trait_values.py b/test/python/test_group_trait_values.py
index 5b97282..8d1463b 100644
--- a/test/python/test_group_trait_values.py
+++ b/test/python/test_group_trait_values.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -43,7 +43,7 @@ class GroupTraitValuesTest(ServerTestCase):
         response, body = self.get("/groups/BXD/traits/10001/values")
         self.assertEqual(response.status, 200)
 
-        values = json.loads(body)
+        values = envelope_data(body)
         self.assertTrue(values)
         bxd1 = next(v for v in values if v["name"] == "BXD1")
         self.assertIsInstance(bxd1["value"], float)
diff --git a/test/python/test_group_traits.py b/test/python/test_group_traits.py
index c9d2125..72abcba 100644
--- a/test/python/test_group_traits.py
+++ b/test/python/test_group_traits.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -46,7 +46,7 @@ class GroupTraitsTest(ServerTestCase):
         response, body = self.get("/groups/BXD/traits", timeout=30)
         self.assertEqual(response.status, 200)
 
-        traits = json.loads(body)
+        traits = envelope_data(body)
         self.assertTrue(traits)
         ids = {record["id"] for record in traits}
         self.assertIn(10001, ids)
@@ -70,7 +70,7 @@ class GroupTraitsTest(ServerTestCase):
 
         response, body = self.get("/groups/BXD/traits?abbreviation=5HT_MB_M")
         self.assertEqual(response.status, 200)
-        traits = json.loads(body)
+        traits = envelope_data(body)
         self.assertEqual(len(traits), 1)
         self.assertEqual(traits[0]["id"], 17985)
         self.assertEqual(traits[0]["abbreviation"], "5HT_MB_M")
@@ -83,7 +83,7 @@ class GroupTraitsTest(ServerTestCase):
         # An unknown abbreviation is an empty list, not an error.
         response, body = self.get("/groups/BXD/traits?abbreviation=no_such_trait")
         self.assertEqual(response.status, 200)
-        self.assertEqual(json.loads(body), [])
+        self.assertEqual(envelope_data(body), [])
 
 
 if __name__ == "__main__":
diff --git a/test/python/test_groups.py b/test/python/test_groups.py
index 0c55a8f..a3dcb55 100644
--- a/test/python/test_groups.py
+++ b/test/python/test_groups.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import database_reachable, HOST, PORT, ServerTestCase
+from server_test_case import database_reachable, HOST, PORT, ServerTestCase, envelope_data
 
 
 
@@ -32,7 +32,7 @@ class GroupsTest(ServerTestCase):
             conn.close()
         self.assertEqual(response.status, 200)
 
-        groups = json.loads(body)
+        groups = envelope_data(body)
         self.assertTrue(groups)
         names = {record["name"] for record in groups}
         self.assertIn("BXD", names)
@@ -53,7 +53,7 @@ class GroupsTest(ServerTestCase):
                 response = conn.getresponse()
                 body = response.read()
                 self.assertEqual(response.status, 200, path)
-                return json.loads(body)
+                return envelope_data(body)
             finally:
                 conn.close()
 
diff --git a/test/python/test_publications.py b/test/python/test_publications.py
index 15c8ab7..883de6f 100644
--- a/test/python/test_publications.py
+++ b/test/python/test_publications.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase, database_reachable
+from server_test_case import HOST, PORT, ServerTestCase, database_reachable, envelope_data
 
 
 class PublicationTraitsTest(ServerTestCase):
@@ -35,7 +35,7 @@ class PublicationTraitsTest(ServerTestCase):
 
         response, body = self.get("/publications/24102824/traits")
         self.assertEqual(response.status, 200)
-        traits = json.loads(body)
+        traits = envelope_data(body)
         self.assertTrue(all(t["pubmed_id"] == 24102824 for t in traits))
         midbrain = next(t for t in traits if t["id"] == 17985)
         self.assertEqual(midbrain["dataset"], "BXDPublish")
diff --git a/test/python/test_search.py b/test/python/test_search.py
index aea1e20..081bdf7 100644
--- a/test/python/test_search.py
+++ b/test/python/test_search.py
@@ -39,7 +39,17 @@ class Gn3StubHandler(http.server.BaseHTTPRequestHandler):
 
     def do_GET(self):
         query = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
-        if "serotonin" in query.get("query", [""])[0]:
+        if query.get("query") == ["wide"]:
+            # 1000 hits, the size of a sorted search's window: more
+            # matches may exist beyond it.
+            body = json.dumps(
+                [
+                    {"name": str(i), "dataset": "WideUnknown", "lrs": float(i)}
+                    for i in range(1000)
+                ]
+            ).encode()
+            self.send_response(http.client.OK)
+        elif "serotonin" in query.get("query", [""])[0]:
             # gn3 has no sort of its own: a sorted /search must ask for a
             # wide page (1000), not just `limit`, to rank across it.
             if query.get("per_page") != ["1000"]:
@@ -139,7 +149,18 @@ class SearchTest(ServerTestCase):
         self.assertEqual(len(hits), 5)
         self.assertEqual(hits[0]["name"], "10199")
         self.assertEqual(hits[0]["dataset"], "C57BL-6JxC57BL-6NJF2Publish")
-        self.assertEqual(body["next"], [])
+        # The envelope: meta, a note on `lod`, and follow-ups -- the next
+        # page (5 hits came back for limit=5) and the top hit's metadata.
+        self.assertIsInstance(body["meta"]["took_ms"], int)
+        self.assertIsInstance(body["meta"]["request_id"], str)
+        self.assertIn("lod = lrs / 4.604", body["notes"])
+        self.assertEqual(
+            [n["href"] for n in body["next"]],
+            [
+                "/search?q=alcohol&limit=5&type=phenotype&page=2",
+                "/traits/C57BL-6JxC57BL-6NJF2Publish/10199",
+            ],
+        )
 
     def test_search_validates_parameters(self):
         self.require_auth()
@@ -147,6 +168,8 @@ class SearchTest(ServerTestCase):
         status, body = self.get("/search?q=%20%20")
         self.assertEqual(status, http.client.BAD_REQUEST)
         self.assertEqual(body["code"], "invalid_parameter")
+        self.assertIsInstance(body["request_id"], str)
+        self.assertIsInstance(body["took_ms"], int)
 
         status, body = self.get("/search?q=alcohol&type=genotype")
         self.assertEqual(status, http.client.BAD_REQUEST)
@@ -250,6 +273,29 @@ class SearchTest(ServerTestCase):
         self.assertEqual(status, http.client.BAD_REQUEST)
         self.assertIn("page", body["detail"])
 
+    def test_search_over_a_full_window_is_partial(self):
+        # A sorted search over a full 1000-hit window cannot know it saw
+        # every match: the response is `partial` and says why. (These hits
+        # are not phenotype datasets, so no database is involved.)
+        self.require_auth()
+
+        status, body = self.get("/search?q=wide&sort=lrs&limit=3")
+        self.assertEqual(status, http.client.OK)
+        self.assertEqual(body["meta"]["state"], "partial")
+        self.assertIn("first 1000 matches", body["notes"][1])
+        self.assertEqual(body["data"][0]["lrs"], 999.0)
+
+        # A window that was not full is complete (the 119 recorded
+        # serotonin hits are BXDPublish ones: complete only if their
+        # locus lookup could reach the database).
+        _, body = self.get(
+            "/search?q=serotonin%20AND%20midbrain%20AND%20group:BXD"
+            "&sort=lod&limit=100"
+        )
+        self.assertEqual(
+            body["meta"]["state"], "complete" if database_reachable() else "partial"
+        )
+
     def test_search_forwards_gn3_parse_errors(self):
         self.require_auth()
 
diff --git a/test/python/test_species.py b/test/python/test_species.py
index 37d8e30..27ac58c 100644
--- a/test/python/test_species.py
+++ b/test/python/test_species.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import database_reachable, HOST, PORT, ServerTestCase
+from server_test_case import database_reachable, HOST, PORT, ServerTestCase, envelope_data
 
 
 
@@ -32,7 +32,7 @@ class SpeciesTest(ServerTestCase):
             conn.close()
         self.assertEqual(response.status, 200)
 
-        species = json.loads(body)
+        species = envelope_data(body)
         self.assertTrue(species)
         for record in species:
             self.assertIn("name", record)
diff --git a/test/python/test_species_by_name.py b/test/python/test_species_by_name.py
index fbaab71..6f31ade 100644
--- a/test/python/test_species_by_name.py
+++ b/test/python/test_species_by_name.py
@@ -9,7 +9,7 @@ import json
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import database_reachable, HOST, PORT, ServerTestCase
+from server_test_case import database_reachable, HOST, PORT, ServerTestCase, envelope_data
 
 
 
@@ -35,7 +35,7 @@ class SpeciesByNameTest(ServerTestCase):
         response, body = self.get("/species/mouse")
         self.assertEqual(response.status, 200)
 
-        species = json.loads(body)
+        species = envelope_data(body)
         self.assertEqual(species["name"], "mouse")
         self.assertEqual(species["full_name"], "Mus musculus")
         self.assertEqual(species["taxonomy_id"], 10090)
diff --git a/test/python/test_species_datasets.py b/test/python/test_species_datasets.py
index e74871d..55eddcd 100644
--- a/test/python/test_species_datasets.py
+++ b/test/python/test_species_datasets.py
@@ -10,7 +10,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -43,7 +43,7 @@ class SpeciesDatasetsTest(ServerTestCase):
         response, body = self.get("/species/mouse/datasets")
         self.assertEqual(response.status, 200)
 
-        datasets = json.loads(body)
+        datasets = envelope_data(body)
         self.assertTrue(datasets)
         names = {record["name"] for record in datasets}
         self.assertIn("Br_U_0803_M", names)
diff --git a/test/python/test_traits.py b/test/python/test_traits.py
index 6a44bd8..850aa8a 100644
--- a/test/python/test_traits.py
+++ b/test/python/test_traits.py
@@ -12,7 +12,7 @@ import socket
 import unittest
 
 from auth_helpers import TOKEN_ENV, auth_server_reachable, auth_token
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 def database_reachable():
@@ -50,7 +50,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/Br_U_0803_M/100001_at")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["category"], "probeset")
         self.assertEqual(info["name"], "100001_at")
         self.assertEqual(info["symbol"], "Cd3g")
@@ -61,7 +61,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/BXD/10001")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["category"], "publish")
         self.assertEqual(info["id"], 10001)
 
@@ -71,7 +71,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/BXDPublish/10001")
         self.assertEqual(response.status, 200)
 
-        info = json.loads(body)
+        info = envelope_data(body)
         self.assertEqual(info["category"], "publish")
         self.assertEqual(info["id"], 10001)
 
@@ -81,7 +81,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/Br_U_0803_M/100001_at/values")
         self.assertEqual(response.status, 200)
 
-        values = json.loads(body)
+        values = envelope_data(body)
         self.assertTrue(values)
         self.assertIn("BXD1", {v["name"] for v in values})
 
@@ -91,7 +91,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/BXD/10001/values")
         self.assertEqual(response.status, 200)
 
-        values = json.loads(body)
+        values = envelope_data(body)
         self.assertTrue(values)
         self.assertIn("BXD1", {v["name"] for v in values})
 
@@ -101,7 +101,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/Br_U_0803_M")
         self.assertEqual(response.status, 200)
 
-        traits = json.loads(body)
+        traits = envelope_data(body)
         self.assertTrue(traits)
         self.assertTrue(all(t["category"] == "probeset" for t in traits))
         self.assertIn("100001_at", {t["name"] for t in traits})
@@ -112,7 +112,7 @@ class TraitsTest(ServerTestCase):
         response, body = self.get("/traits/BXD")
         self.assertEqual(response.status, 200)
 
-        traits = json.loads(body)
+        traits = envelope_data(body)
         self.assertTrue(traits)
         self.assertTrue(all(t["category"] == "publish" for t in traits))
         self.assertIn(10001, {t["id"] for t in traits})
diff --git a/test/python/test_version.py b/test/python/test_version.py
index 2fb46e9..32f08d5 100644
--- a/test/python/test_version.py
+++ b/test/python/test_version.py
@@ -4,7 +4,7 @@ import http.client
 import json
 import unittest
 
-from server_test_case import HOST, PORT, ServerTestCase
+from server_test_case import HOST, PORT, ServerTestCase, envelope_data
 
 
 class VersionTest(ServerTestCase):
@@ -18,7 +18,7 @@ class VersionTest(ServerTestCase):
             conn.close()
         self.assertEqual(response.status, 200)
 
-        record = json.loads(body)
+        record = envelope_data(body)
         self.assertEqual(record["name"], "GeneNetwork4")
         self.assertEqual(record["short_name"], "GN4AI")
         self.assertEqual(record["version"], 4.0)