hivemq/hivemq-edge/trace-error-messages

Trace Error Messages

Systematic approach to locating error message sources before writing test assertions.

Rule: Never assume an error message. Trace it to its source first.

When to invoke

Invoke this skill when:

• A Cypress assertion on error text is failing
• You are writing a new test for an error state
• The user asks "why is this error message showing?"
• You need to mock an API error in a test
• You are adding error state coverage to a form or page

Stack layers

Errors flow through these layers — identify which layer owns the message before writing assertions:

API Definition (OpenAPI)
    ↓
Generated Service (src/api/__generated__/services/)
    ↓
React Query Hook (src/api/hooks/)
    ↓
MSW Mock Handler (src/api/hooks/[hook]/__handlers__/)
    ↓
React Component (error display: Toast / Alert / inline)
    ↓
RJSF Form (client-side validation only)
    ↓
Page Object (cypress/pages/)
    ↓
Cypress Test (cypress/e2e/)

Decision tree — start here

Is this a form validation error (before any API call)?
├─ YES → Step 5 (RJSF). Check JSON Schema required fields.
│         Assert on the RJSF error summary panel.
│
└─ NO → Is this an API error?
         ├─ YES → Steps 1–4. Trace: OpenAPI → hook → MSW handler → component.
         │
         └─ NO → Network/timeout error → Step 4. React Query + generic error UI.

7-step tracing guide

Step 1 — OpenAPI service definition

Where: src/api/__generated__/services/[ServiceName].ts

Find the errors object — these are the API contract messages:

errors: {
  400: `Bridge is invalid`,  // ← this becomes ApiError.message
  401: `The requested credentials could not be authenticated.`,
}

The errors field values propagate as ApiError.message. They are not what the UI displays — components usually show a different i18n key or ApiError.body.title.

Step 2 — React Query hook

Where: src/api/hooks/[hookName]/[hookName].ts

Verify the error type: useMutation<Success, ApiError, Input>.

ApiError contains:

• message — status text from the OpenAPI errors object
• body.title — human-readable message from the response body
• status — HTTP status code

The component typically displays err.body.title, not err.message.

Step 3 — MSW mock handler

Where: src/api/hooks/[hookName]/__handlers__/index.ts

This controls what error the test actually sees. If an error handler does not exist yet, add one:

http.post('*/endpoint', () => {
  return HttpResponse.json({ title: 'Your error text here' }, { status: 400 })
})

The title in the response body is what ApiError.body.title contains — and what the component displays.

Step 4 — React component

Where: src/modules/[Module]/components/[Component].tsx

Find where the hook's error is consumed:

• .catch((err: ApiError) => ...) on mutations
• error property from useQuery

Identify what the component actually renders:

• err.body.title → the server-provided message (from the MSW handler)
• t('some.key') → a generic i18n message
• Both mixed (generic title + specific detail from err.body.title)

Step 5 — RJSF client-side validation

Where: JSON Schema for the form (in src/api/schemas/ or inline in the component)

RJSF generates error messages automatically from the schema:

• Required field: "[fieldName] is a required property"
• Format error: "[fieldName] must match format 'email'"

These appear before any API call. Assert on the RJSF error summary panel:

cy.get('[role="alert"] ul li').eq(0).should('contain.text', 'id is a required property')

Step 6 — Page Object getter

Where: cypress/pages/[Module]/[ModulePage].ts

Check whether an error getter already exists:

grep -r "error\|alert\|toast" cypress/pages/[Module]/ --include="*.ts"

If not, add one. Never use raw selectors in test bodies.

Step 7 — Cypress test

Write assertions only after completing steps 1–6. Use the exact message from whichever layer owns it:

// RJSF validation (step 5 message)
bridgePage.config.errorSummaryItem(0).should('contain.text', 'id is a required property')
// API error (step 3 MSW body.title)
loginPage.errorAlertMessage.should('have.text', 'Invalid username and/or password')

Use contain.text for partial matches when message format may evolve. Use have.text for exact matches on critical UX strings.

Error Message Source Matrix

Do and don't

Do:

• Trace the full stack before writing any assertion
• Use partial matches (contain.text) when message format may change
• Create page object getters for error containers before writing assertions
• Comment the error source in the test: // MSW handler: body.title
• Test RJSF validation and API errors as separate test cases

Don't:

• Assume the error text — always verify in source
• Hard-code DOM selectors in test bodies (use page objects)
• Mix up client validation errors and API errors in the same assertion
• Test toast errors with Percy — timing makes snapshots unreliable