@manta-eu/client 0.12.0 → 0.13.0

package/README.md

@@ -56,11 +56,55 @@ const client = mantaGraphQLClient(new URL("https://app.hiremanta.com"), onSigned
 | `./shared/*`     | Contract pieces shared with the server — page context, models, datastore paths, RDF namespaces |
 | `./types/*`      | Standalone type modules                                                                        |
 | `./shared/tools` | Tool definitions the assistant is given                                                        |
+| `./testing`      | An in-memory Manta for testing your app's SPARQL reads and writes                              |
 
 Most consumers reach this package through [`@manta-eu/react`](https://www.npmjs.com/package/@manta-eu/react),
 which mounts the copilot and its providers for you. Use it directly when you want the contract
 without the UI.
 
+## Testing your app
+
+`createMantaMock` from `@manta-eu/client/testing` answers `/sparql` and `/sparql-update` from an
+in-memory store, so tests run your app's real LDKit queries without a Manta stack. It adds the
+prefixes Manta declares, to the seed Turtle too, and refuses the writes Manta refuses: anything but `INSERT DATA`, `DELETE DATA`
+and `DELETE`/`INSERT` with a scoped `WHERE`, and writes that name a graph.
+
+It runs on Comunica and N3, which only tests need, so add them as dev dependencies:
+
+```bash
+pnpm add -D @comunica/query-sparql-rdfjs-lite n3@^1.26.0
+```
+
+Pass its `fetch` wherever your code takes one, with absolute URLs. As on Manta, reads go to
+`/sparql` and writes to `/sparql-update`:
+
+```typescript
+import { createMantaMock } from "@manta-eu/client/testing";
+import { createLens } from "ldkit";
+
+const manta = createMantaMock({ turtle: "<https://example.com/todo/1> a <https://example.com/Todo> ." });
+const reads = createLens(TodoSchema, { sources: ["https://manta.test/d/acme/sparql"], fetch: manta.fetch });
+const writes = createLens(TodoSchema, { sources: ["https://manta.test/d/acme/sparql-update"], fetch: manta.fetch });
+```
+
+In Playwright, route the page's SPARQL requests to it:
+
+```typescript
+import { createMantaMock, mantaMockRoutePattern } from "@manta-eu/client/testing";
+
+test.beforeEach(async ({ page }) => {
+  const manta = createMantaMock();
+  await page.route(mantaMockRoutePattern, manta.route);
+});
+```
+
+`mantaMockRoutePattern` matches `/sparql` and `/sparql-update` on any origin. Pass a narrower pattern, such
+as `https://manta.test/**`, when the page also queries other SPARQL endpoints. Requests the mock
+does not serve fall through to the network. Like Manta, it answers a cross-origin page with CORS headers for that
+origin, and answers the preflight of a write itself.
+
+`manta.updates` lists the updates it applied, in order. Every datastore path shares one store.
+
 ## License
 
 MIT