Conformance and deployment checks
Run the connector's published test suite and diagnose signing, mapping, and pagination failures.
@askdepth/audience-connectorv0.1.2On this page
The published connector includes a conformance CLI. Run it against your endpoint before using the Askdepth connection wizard. The platform uses conformance as an activation gate.
Run the suite
Set ASKDEPTH_SECRET in your server or CI environment, then run:
npx @askdepth/audience-connector@0.1.2 conformance \
--url http://localhost:8080/askdepth/v1 \
--unmapped-column internal_notes \
--filter-only-attribute country=PLUse an unmapped column that actually exists in your store. Use a filter-only attribute that you actually declared but did not make returnable. Replace the example names and value with your own test fixture.
The CLI reads ASKDEPTH_SECRET when --secret is absent and ASKDEPTH_PREVIOUS_SECRET when --previous-secret is absent. Keep CI output and command tracing from disclosing those values.
Options and exits
| Option | Purpose |
|---|---|
--url | Complete base URL, including /askdepth/v1 or your configured prefix. |
--secret | Active secret; environment fallback is supported. |
--previous-secret | Previous secret for rotation overlap checks. |
--unmapped-column | Repeatable source columns that must not appear in responses. |
--filter-only-attribute name[=value] | Repeatable; adding a value exercises an actual filter rather than only structure. |
--case | Repeatable case IDs for diagnosis. Run the complete suite before activation. |
--json | Machine-readable report. |
--timeout-ms | Per-case timeout, default 5000. |
Exit 0 means all selected cases passed, 1 means a case failed, and 2 means usage, connection, or runner failure. A localhost pass validates your local endpoint; it does not prove Askdepth can reach your deployed hostname.
What the suite checks
Seven positive cases cover health, schema, count, canonical search/pagination, explicit external IDs, attribute filtering, and suppression. Eight negative cases cover unsigned access, invalid signatures, unmapped-column leakage, unsafe errors, unstable cursors, row caps, falsely advertised random sampling, and exposed write methods.
Without representative fixture data and the extra column/attribute arguments, some cases can exercise only structure. A passing suite is useful evidence about the tested endpoint and data, not a proof of every possible privacy or correctness property.
Common failures
| Symptom | Inspect first |
|---|---|
| GET fails but POST verifies | GET must sign an empty body; do not require GET content-type. |
| Every signature fails | Exact raw body, UTF-8 secret, seconds versus milliseconds, and duplicate v1= prefix. |
shim_misconfigured | Express body was parsed before the shim; preserve raw bytes. |
| Health/schema pass but count/search fail | Request mapping is source column → canonical field; connector configuration is the reverse. |
| Duplicate or missing candidates across pages | Cursor binding, stable ordering, and unchanged query between pages. |
| Filter-only data appears in rows | Separate filterable from returnable attributes. |
unsupported_capability | Health advertises only flags your adapter actually supports. |
| Count equals a page size | Return an exact count, not a truncated fetch length. |
Connect the deployed endpoint
Deploy behind HTTPS, keep the signing secret on your server, and confirm the complete base URL is reachable by the platform. Do not expose database credentials in the URL or mapping response. Health checks are signed; do not add an unsigned bypass to the four contract routes for monitoring.
In the workspace, open Settings → Integrations → Data sources, provide the endpoint, inspect the declared columns, and configure the field mapping. Conformance must pass before activation. Repeat the complete suite after changes to adapters, mappings, raw-body middleware, cursors, or secret rotation behavior.