Test a Praxa integration end to end

Tests pass at different evidence levels. A package import proves the artifact can load. A mocked request proves client behavior. A live authenticated canary proves the deployed boundary. A user test proves the workflow is understandable and usable. Record each result separately.

Prerequisites

Before you begin, prepare:

a written success criterion and proof boundary for the integration under test;
synthetic tenants, subjects, credentials, and lifecycle fixtures;
redacted observability fields and a secure location for test evidence;
an owner for rollback, cleanup, and unresolved qualification gaps;
an acceptance assertion that proves every required package, auth, isolation, replay, outage, lifecycle, and cleanup lane is recorded.

1. Record the test subject

Before testing, capture:

package versions:
application commit:
Praxa API plane:
Praxa deployment origin and version:
tenant IDs used:
subject IDs used:
credential scopes:
test start and end time:
cleanup owner:

Never put token values, provider credentials, customer content, or webhook secrets in the receipt.

2. Prove the public packages

Use an empty temporary project rather than an existing node_modules tree:

mkdir praxa-package-smoke && cd praxa-package-smoke
npm init -y
npm install --ignore-scripts --no-audit --no-fund \
  @praxa/sdk@0.3.0 \
  @praxa/mcp-contracts@0.3.0

node --input-type=module -e '
  const sdk = await import("@praxa/sdk");
  const memory = await import("@praxa/sdk/memory");
  const mcp = await import("@praxa/mcp-contracts");
  if (typeof sdk.PraxaClient !== "function") throw new Error("missing PraxaClient");
  if (typeof memory.MemoryFederation !== "function") throw new Error("missing MemoryFederation");
  if (mcp.PRAXA_MCP_TOOLS.length !== 12) throw new Error("unexpected MCP surface");
  console.log("Praxa package smoke passed");
'

This proves registry installation and module exports. It does not prove a live Gateway or provider.

3. Run the API-key matrix

Create disposable personal-workspace keys with deliberately different scopes:

Key	Scopes	Purpose
Task writer	`execute:write`	Submit only
Run reader	`runs:read`	Read and stream only
Run manager	`runs:read`, `runs:write`	Webhooks and cancellation
Usage reader	`usage:read`	Usage only
Memory reader	`memory:read`	Query and export only
Memory writer	`memory:write`	Create and erase only

For every route, test:

The correct key succeeds.
A valid wrong-scope key fails closed.
A revoked formerly-correct key fails closed.
A malformed key fails with an authentication problem and no secret reflection.
A resource ID from another tenant is not projected.

4. Test idempotency

For each mutation:

A. Send request body X with key K -> success resource R
B. Send exact body X with key K -> same logical resource R
C. Send different body Y with key K -> 409 conflict
D. Send body Y with a fresh key J -> new logical request

Do not generate a new key for a network retry. Do not reuse a key for new work.

5. Test tenant and subject isolation

Use two disposable tenants and two subjects per tenant:

Request	Expected
Tenant A, subject 1 reads its record	Present
Tenant A, subject 2 reads subject 1’s record	Absent
Tenant B, subject 1 reads tenant A’s record	Absent
Caller supplies an owner or tenant field	Rejected or ignored by a server-derived boundary

Run this matrix for hosted memory candidates and any provider namespace mapper used by @praxa/sdk/memory.

6. Test memory degradation and provenance

Query two healthy sources and record their source IDs.
Disable one source and require aggregate partial, not ok and not an unexplained empty result.
Disable every source and require aggregate failed returned with source errors.
Return exact matching kind and text from two sources and require both matches to remain.
Return contradictory text and require separate items.
Verify every displayed memory can be traced to source, provider, record ID, origin, confidence, and capture time.

7. Test streams and webhooks

For SSE:

disconnect after a known event ID;
reconnect with Last-Event-ID;
require increasing IDs with no event after a terminal state;
distinguish heartbeat comments from data events;
treat EOF before terminal as incomplete unless the API documents otherwise.

For webhooks:

verify the HMAC before parsing JSON;
reject an expired timestamp and modified body;
deliver the same immutable event_id twice and require one logical effect;
process one run by sequence, not HTTP arrival order;
return 2xx only after durable acceptance.

8. Test deletion and cleanup

For hosted candidates:

Delete using a stable idempotency key.
Replay the deletion and require the same receipt.
Query and export to confirm the candidate content is gone.
Confirm the deletion receipt contains no content.
Confirm the provider-owned source still exists unless you separately delete it there.

After every canary:

revoke disposable keys and tokens;
disable test webhook endpoints;
remove disposable provider records;
keep only non-secret receipts and identifiers needed for audit;
record any verification that could not run.

Completion criteria

Call an integration production-qualified only when the package, application, authenticated API, negative authorization, isolation, degraded-state, cleanup, and user-workflow lanes required by that integration have all passed. A green subset must stay labeled as that subset.

Troubleshooting

Symptom	Resolution
Dashboard says success but outcome is unknown	Require terminal readback or an explicit incomplete verification state.
Metrics cannot be correlated	Carry safe request, run, event, delivery, trace, and test identifiers across boundaries.
Logs contain sensitive data	Stop collection, rotate exposed credentials, and replace raw payloads with bounded metadata.
One green test is treated as production proof	Track package, mock, authenticated runtime, deployment, and user verification separately.

Best practices

Define the expected observable result before running the test.
Separate positive, denial, isolation, replay, degraded-state, and cleanup lanes.
Use synthetic data and credential fingerprints rather than secrets.
Record unresolved checks as pending instead of inferring success.
Keep rollback and owner information beside the release evidence.

Optimize for production

Run cheap contract and fake tests before authenticated canaries.
Parallelize only independent test lanes and cap external side effects.
Sample high-volume telemetry while retaining every denial, conflict, and terminal failure.
Measure pass rate, p50/p95 latency, retry budget, isolation failures, cleanup completion, and time to diagnose.

Optimize only after the correctness and isolation matrix passes. Lower latency or cost is not an improvement if verified outcomes, authority checks, or recovery rates regress.

Cleanup and next steps

Revoke every disposable key and OAuth grant.
Remove test endpoints, provider records, candidates, and local artifacts.
Close or explicitly record unresolved runs and verification gaps.
Publish only redacted results, exact versions, timestamps, and rollback instructions.

After cleanup, run the shared integration test matrix and record any environment-specific check that remains pending.

Frequently asked questions

What proves this tutorial works?

The minimum observable result is that every required package, auth, isolation, replay, outage, lifecycle, and cleanup lane is recorded. A compile, package import, mocked response, or initial admission alone does not prove the complete workflow.

Can a browser, mobile app, or model prompt hold the credential?

No. Evidence contains credential fingerprints and safe identifiers, never live credentials or raw sensitive payloads.

How should an ambiguous mutation be retried?

Persist the exact logical input and idempotency key before the first attempt. Reconcile through authoritative readback or replay the exact request with that same key before creating new work.

What should we monitor after release?

Monitor test pass rate, p50/p95 latency, authorization denials, replay conflicts, isolation failures, cleanup completion, and diagnosis time. Alert on authorization bypass, cross-tenant disclosure, repeated conflicts, or cleanup failure.

Get started

Core Concepts

Releases

Test a Praxa integration end to end

Prerequisites

1. Record the test subject

2. Prove the public packages

3. Run the API-key matrix

4. Test idempotency

5. Test tenant and subject isolation

6. Test memory degradation and provenance

7. Test streams and webhooks

8. Test deletion and cleanup

Completion criteria

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?

​Prerequisites

​1. Record the test subject

​2. Prove the public packages

​3. Run the API-key matrix

​4. Test idempotency

​5. Test tenant and subject isolation

​6. Test memory degradation and provenance

​7. Test streams and webhooks

​8. Test deletion and cleanup

​Completion criteria

​Troubleshooting

​Best practices

​Optimize for production

​Cleanup and next steps

​Frequently asked questions

​What proves this tutorial works?

​Can a browser, mobile app, or model prompt hold the credential?

​How should an ambiguous mutation be retried?

​What should we monitor after release?

Prerequisites

1. Record the test subject

2. Prove the public packages

3. Run the API-key matrix

4. Test idempotency

5. Test tenant and subject isolation

6. Test memory degradation and provenance

7. Test streams and webhooks

8. Test deletion and cleanup

Completion criteria

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?