Home/Field Guide/Security & operations
CONCEPT 27
Testing and troubleshooting runbook
Turn symptoms into targeted checks across the application, API, runtime, and index.
Work one layer at a time
| Symptom | First proof | Then investigate |
|---|---|---|
| Module deployed, feature missing | Bundle and DS component states | Imports, references, config, and activation errors |
| Widget mounted, blank output | Console, network, registered tag | Asset paths, script mode, initialization, and API response |
| Form saves, entry missing from list | Direct record read as same user | Workflow status, scope, and search index |
| API works only for admin | Compare identity and scopes | Role grants, resource permissions, and site/account boundary |
| Import completes with missing data | Task errors and ERC sample | Dependency ordering, validation, and replay strategy |
| Release changes behavior | Reproduce on both exact builds | Feature flags, breaking changes, compatibility, and config |
Build the regression suite
Keep unit tests for business rules, then exercise the module or extension in a real target runtime. Test endpoints with normal identities, verify UI state and keyboard navigation, and cover a denied path. Add a migration fixture with relationships, multiple locales, and an attachment. Document the expected trace and stable IDs so the same suite can be run after a patch.
Record evidence while debugging
Log the target build, exact URL or command, actor role, scope, request correlation, and a redacted response. If retrying changes the result, establish whether a job or cache made the first outcome eventually consistent. Keep the diagnostic trail attached to the smallest reproducible case.