Skip to content

Latest commit

 

History

History
186 lines (152 loc) · 15.4 KB

local-testing.md

File metadata and controls

186 lines (152 loc) · 15.4 KB

Test your app with a Pod

The app and the Pod are separate services. Run the app on your machine while choosing either a hosted HTTPS Pod or a local Pod as the data service. Use a context made for testing, with synthetic data and a user who can grant access.

Choose a setup

Setup App URL Pod URL What you need
Local app, hosted Pod http://127.0.0.1:5173/ Your full HTTPS Pod URL A working account and a test context; Pod support for loopback callbacks/dynamic clients
Local app, local Pod http://127.0.0.1:5173/ For example http://localhost:8090/demo Running Pod, configured identity provider, provisioned owner and test context
Deployed app, hosted Pod Your HTTPS app origin Your full HTTPS Pod URL Deployment identity and routing, then the same checks below

Use the full Pod address, including a path such as /alice or /demo, rather than just its hosting server. Keep the local app hostname and port fixed between login and callback; localhost and 127.0.0.1 have different browser storage. Loopback HTTP is an explicit development exception, not an option for a remote HTTP server. Use HTTPS for phone/remote testing; the phone's loopback is the phone.

Local frontend, hosted Pod

Follow the quickstart, then run:

npm run dev -- --host 127.0.0.1 --port 5173 --strictPort

The dynamic runtime configuration includes development: 'loopback-http'. That permits the local HTTP callback and, if used, local HTTP Pod endpoints. It does not relax validation of a remote Pod or make the hosted Pod accept an unsupported client policy. Enter its full HTTPS URL in the app's sign-in form, sign in on the Pod's page, grant only the test context, return to the app and explicitly select it.

A successful sign-in without a writable context is not setup completion for an app that writes; an app that only reads needs a readable one. The owner must create or grant it through their Pod's supported administration tools. Context administration is outside this SDK's current operation set. Do not fix missing access by inventing a scope or choosing a different context silently.

Running a local Pod

The Kotlin implementation's quick start is the operator reference. At the revision checked for this guide it needs Java 25 and Docker Compose. In that checkout, for a fresh local setup:

docker compose -f deployments/local/compose.yaml up -d
cp deployments/local/env/local.example.env deployments/local/env/local.env
./gradlew :deployments:sempods:image:run

Do not overwrite an existing local.env; inspect and adapt it instead. Follow the same upstream quick start to provision a development Pod, and its identity guide to configure person login. The identity service setup requires a configured upstream provider; starting MongoDB and the Pod alone does not create a working sign-in account. If you do not want to operate this stack, use a hosted test Pod.

The example server listens on port 8090. After provisioning demo, this is a credential-free discovery check:

curl http://localhost:8090/demo/.well-known/oauth-protected-resource

Open the app and connect to http://localhost:8090/demo. The Pod's configured public base URL must match its actual canonical address: it determines identities and token issuer values. Changing a port or hostname is not a harmless alias. Keep the development server and its published development admin configuration local. Provisioning credentials belong in the operator setup, never the frontend.

This setup description was checked against Kotlin revision 6b92806982528479347bf35336460516dd3fdefb. Use the instructions matching your checkout and record your revision; it is not a claim of a completed live login.

Walk through one complete app

Run these checks against the installed SDK revision and record the result, Pod version, app origin and browser. Keep credentials and private data out of reports.

Check Expected observation
Connect and consent Sign-in occurs on the Pod/provider; the callback returns to the app; context choice is explicit
Cancel sign-in Visible cancellation/failure; existing connections and drafts remain usable where eligible
Change sharing with an existing grant The Pod shows its consent page, also when it would reuse the grant for a sign-in; a changed choice of contexts shows after the return
Cancel Change sharing The earlier session resumes with the same context and data; the app says that sharing was not changed and offers Change sharing as the one action
Create, list, complete, reopen, rename, delete Correct resource in the selected context; list updates after confirmed writes; deletion checks the version the person saw
Reload Accepted connection restores; the last readable context is selected again; no app-owned token handling
Change target with a draft Leaving requires confirmation; cancelled navigation preserves the draft
Concurrent change to the same title Save offers comparison with the Pod version and preserves the local draft
Concurrent change to a different mapped field The bounded rebase preserves both changes when its evidence permits; otherwise review is explicit
Lose a write's response The UI says unconfirmed and offers inspection of the captured resource; no blind resend or duplicate creation
Remove write access on the Pod Readable data/draft remains; writes become disabled after access revalidation
Remove read access on the Pod Ineligible server data is cleared after revalidation; no fallback to another context
Second tab One tab holds the runtime; the other shows busy rather than taking it over
Another Pod Sequential connection leaves the first connection available; switching remains guarded
Pod overview with on-demand Contexts The overview loads without a context choice or catalogue request; a refused read shows as failed; editing a row opens it in its own context with no context chooser and no selection change
Language, phone layout, keyboard Labels and feedback are understandable; locale changes preserve drafts; controls remain reachable

A local app signs in as a dynamically registered client, for which the Pod shows consent on every interactive sign-in. Whether a sign-in reuses the grant while Change sharing still asks therefore shows only with a deployed did:web app.

For concurrent edits, use another browser profile, a private window or another device. Two tabs in the same profile intentionally exercise the busy state. Access changes require a Pod operator or owner and become visible on revalidation, not through an assumed server push. To test a lost answer deterministically use a controlled test fixture/proxy that applies the write and withholds its response; simply going offline before clicking Save tests a different condition. The SDK's automated browser fixtures exercise uncertainty without real data. Report a manual uncertainty check as untested if you cannot reproduce it safely.

Test an app that only reads

An app that only reads, such as a data explorer or a Pod overview, skips the create, edit and conflict checks above. It needs two other things: consent that grants no more than it reads, and evidence that it never writes.

Consent. An app cannot ask a Pod for read access only. The person chooses the contexts on the Pod's consent screen; whether they can grant read access alone depends on the Pod. Grant only the contexts the app reads, read-only where the consent screen offers it. Leaving out write calls restricts the app's code, not the access it holds, and the consent screen cannot show the difference. The architecture decisions explain why the SDK has no read-only mode.

No write path. For an overview, usePodLoad (typically with contextSelection="on-demand" on the provider) receives a BoundPod, which offers only sparql.select and sparql.construct: no write operation exists on it. Context reads through useLoad or useList are reads too, but every BoundView, for example from useView, useAppState().view or useLoad's read function, also carries subjects.put, patch and delete. Do not call those, and do not use useCreation, useFieldUpdate, useResourceEditor, ResourceEditor, bindResourceEditor or the @sempods/client-sdk/edit write helpers (createResourceEditor, prepareCreation, updateFields, removeSnapshot). A test that fails when the app's source uses one of these keeps it that way; the SDK does not ship one.

Lost access in an overview. A usePodLoad result does not react to a lost Context grant: the Pod reader stays usable and the shown rows are not cleared. The Pod enforces the change on the next query, so give the overview an explicit reload.

Real data. Run the checks below against a test context with synthetic data first. An explorer is often meant for a Pod with real data: connect it only after the network check passed, with the person's explicit agreement, and record which contexts it reads in the app's notes.

Check Expected observation
Connect and consent Only the contexts the app reads are granted; an on-demand overview loads without a context choice
Loading, empty and failed Loading, an empty result and a failed read look different; a refused or failed read never shows as empty
Read access only Where the Pod lets you grant read access alone, the app works fully; a read-only notice (AccessNotice) is expected
Remove read access, Context reads For useLoad/useList, displayed data is cleared after revalidation; no fallback to another context
Remove read access, Pod overview A usePodLoad result stays on screen; after reload() it no longer contains that Context's data
No writes The browser's network panel over a full session shows no PUT, PATCH or DELETE; POST only for queries, sign-in and token renewal
Reload, second tab, language As in the complete walkthrough

Queries are sent as POST to the Pod's /_system/sparql/query; sign-in (client registration, token exchange) and token renewal also use POST. Treat any other POST to the Pod as a possible write and find its caller.

When a step fails

Symptom Check first
Callback is a 404 or shows a hosting error Serve the same app at /callback; for a subpath, use its matching callback and rewrite
Callback rejected or login appears lost Exact app origin/path, app DID, stable port, stored attempt, fresh sign-in; use recovery
Pod rejects the deployed app at sign-in Pod's host allow-list and DID document
Discovery fails Full Pod URL, advertised endpoints, HTTPS/loopback policy, network and server version
Browser reports CORS Pod/proxy OPTIONS handling and exposed headers; keep SDK requests cookie-free
No contexts or no write controls Actual context grants and current catalogue; feature scopes are separate
Busy/unavailable storage Close the other active tab, or use a browser/profile with IndexedDB and Web Locks; do not add a memory fallback

The inspected Kotlin CORS filter supports cookie-free bearer requests from other origins; a new Netlify domain does not inherently require its credentialed-origin allowlist. A proxy can still break preflight or hide ETag/auth headers. Diagnose that server configuration instead of disabling browser protections or proxying credentials through an arbitrary service.

Finish with the deployed-origin smoke test.