Fix timeout error messages in JavaScript client

[evanniedojadlo]

Summary

Fixes #64 - Two tests in tests/js/auto-wait.test.js were failing because timeout errors displayed as [object Object]: undefined instead of helpful error messages like timeout: Timeout after 1000ms waiting for '#selector': element not found.

In Vibium fashion, I leveraged Claude Code to identify and address this issue, then personally tested and verified the fixes on macOS 26.1.

The Issue

When find() timed out looking for a non-existent element, the error message was completely unhelpful:

Error: [object Object]: undefined

Instead of something like:

Error: timeout: Timeout after 1000ms waiting for '#does-not-exist': element not found

Failing tests:

• ✖ find() times out for non-existent element
• ✖ timeout error message is clear

Root Cause

The BiDi client was attempting to create error messages by directly stringifying the error response, but error responses can come in two different formats:

1. Flat format (BiDi spec): { error: "timeout", message: "Timeout after 1s..." }
   • Used by browser-native BiDi errors
2. Nested format: { error: { error: "timeout", message: "..." } }
   • Currently sent by custom vibium: commands

The client was only handling the flat format, causing the nested format to stringify as [object Object].

The Fix

Updated the JavaScript BiDi client to detect and handle both error response formats:

Key changes in clients/javascript/src/bidi/client.ts:

if (response.type === 'error' && response.error) {
  // Handle both flat and nested error formats for compatibility
  let errorCode: string;
  let errorMessage: string;

  if (typeof response.error === 'object' && response.error !== null) {
    // Nested format: { error: { error: "code", message: "msg" } }
    const errObj = response.error as { error?: string; message?: string };
    errorCode = errObj.error || 'unknown error';
    errorMessage = errObj.message || 'An error occurred';
  } else {
    // Flat format (BiDi spec): { error: "code", message: "msg" }
    errorCode = String(response.error);
    errorMessage = response.message || 'An error occurred';
  }

  pending.reject(new Error(`${errorCode}: ${errorMessage}`));
}

Updated TypeScript types in clients/javascript/src/bidi/types.ts:

export interface BiDiResponse {
  id: number;
  type: 'success' | 'error';
  result?: unknown;
  error?: string | { error?: string; message?: string }; // Can be flat (spec) or nested (current impl)
  message?: string;
}

Test Plan

All 5 auto-wait tests now pass:

• ✔ find() waits for element to appear
• ✔ click() waits for element to be actionable
• ✔ find() times out for non-existent element
• ✔ timeout error message is clear
• ✔ navigation error message is clear

Testing with Claude Code

To verify the fix:

Run the failing tests:

node --test tests/js/auto-wait.test.js

You should see all 5 tests pass with proper error messages displayed when timeouts occur.

Claude Code prompts for testing:

# Test timeout error messages
Run the auto-wait tests and verify that timeout errors show helpful messages instead of [object Object]

# Test error format compatibility
Verify the client handles both flat (BiDi spec) and nested error response formats correctly

Files Changed

• clients/javascript/src/bidi/client.ts - Added error format detection logic
• clients/javascript/src/bidi/types.ts - Updated TypeScript types to support both formats

🤖 Generated with Claude Code