Don't show users a raw Playwright error — translating exceptions into friendly messages

When Playwright encounters an error, the exception message often includes a lengthy block of debug information starting with "Call log:". This detailed trace is valuable for developers troubleshooting issues, but presenting it to end-users through a maintenance tool offers little to no clarity about the actual problem.

Stringifying a Playwright exception object frequently produces not only the description of the failed operation but also several lines of internal logging detailing what the library attempted internally. The structure of the problem becomes evident when Playwright experiences a timeout. The exception message might read: "Timeout 30000ms exceeded.

Call log: - navigating to 'https://example.com/wp-admin/', waiting until 'load' - navigation interrupted by another navigation to 'https://example.com/wp-login.php' ...". The initial line conveys a meaningful message, whereas everything following "Call log:" represents internal processing steps that are irrelevant to the end user. Displaying this raw data front and center fails to provide users with a clear path forward.

To rectify this, the solution involves examining the exception message, matching it against common error patterns, and returning a concise, type-specific explanation when a match is found. If no match is identified, the approach defaults to using only the first line of the message, truncated to a maximum of 120 characters if necessary.

The implementation of this logic is demonstrated in the example Python function `_friendly_error(e) -> str:`. The function first retrieves the string representation of the exception. If the error type is identified as a timeout or contains the word "timeout", it returns a specific timeout-related message. Similarly, checks are performed for DNS errors, connection refusals, SSL certificate errors, and login failures, each returning a tailored message.

In the case of unrecognized errors, the function extracts the first line of the message and returns it, ensuring the output remains concise and user-friendly.

The order of checking error types is crucial, as the presence of the word "timeout" within the message string can sometimes indicate a timeout error. Additionally, Chromium-specific error codes, prefixed with "net::ERR_", provide reliable patterns for matching DNS errors, connection refusals, and SSL certificate issues. When no specific pattern matches, the function defaults to returning only the first line of the exception message, ensuring that even unknown errors are presented in a manageable format.

This design approach addresses a fundamental aspect of error handling: distinguishing between the information necessary for developers to debug issues versus the information essential for users to understand what went wrong. By displaying only a short, actionable message to users while still logging the detailed exception for debugging purposes, the system maintains a clear separation of responsibilities.

This not only enhances user experience by providing clear guidance but also ensures that developers retain access to comprehensive error data without cluttering user interfaces with unnecessary technical details. This method effectively encapsulates the broader principle of tailoring detailed error information for developers and crafting user-friendly messages, illustrating a critical design consideration in software development.