Better errors from visitable (#640)

* Better errors from visitable

This adds the actual error message from Ember's router to the (too generic) message from `visitable`. This is especially important when your test needs to know what kind of error was triggered. For example some tests might want to handle `TransitionAborted` errors differently, see emberjs/ember-test-helpers#332 (comment).

* Pass original error message from visit as Error#cause

* preserve original error instance

...under the `cause.error`

* doc: add a brief note about the `cause.error`

in the `visitable` error instance

---------

Co-authored-by: Ruslan Hrabovyi <kudgo.test@gmail.com>

addon/src/-private/better-errors.js

@@ -25,6 +25,7 @@ export function throwBetterError(node, key, error, { selector } = {}) {
   const wrapperError = new PageObjectError(message, {
     cause: {
       message,
+      error: error.cause,
       key,
       node,
       selector,

addon/src/properties/visitable.js

@@ -127,7 +127,9 @@ function appendQueryParams(path, queryParams) {
  * @param {string} path - Full path of the route to visit
  * @return {Descriptor}
  *
- * @throws Will throw an error if dynamic segments are not filled
+ * @throws Will throw an error if dynamic segments are not filled.
+ *         Note: An error instance may contain a `cause.error` property
+ *         with the original error thrown by an underlying test helper.
  */
 export function visitable(path) {
   return action(function (dynamicSegmentsAndQueryParams = {}) {
@@ -138,8 +140,10 @@ export function visitable(path) {
 
     return getAdapter()
       .visit(fullPath)
-      .catch(() => {
-        throw new Error(`Failed to visit URL '${fullPath}'`);
+      .catch((e) => {
+        throw new Error(`Failed to visit URL '${fullPath}': ${e.toString()}`, {
+          cause: e,
+        });
       });
   });
 }

test-app/tests/unit/-private/properties/visitable-test.ts

@@ -108,11 +108,21 @@ module('visitable', function (hooks) {
     } catch (e) {
       assert.strictEqual(
         e?.toString(),
-        `Error: Failed to visit URL '/non-existing-url/value'
+        `Error: Failed to visit URL '/non-existing-url/value': UnrecognizedURLError: /non-existing-url/value
 
 PageObject: 'page.foo("[object Object]")'
   Selector: '.scope'`
       );
+
+      const originalError = (e as any).cause.error;
+      assert.true(
+        originalError instanceof Error,
+        '`cause.error` is an instance of `Error`'
+      );
+
+      assert.strictEqual(originalError.name, 'UnrecognizedURLError');
+
+      assert.strictEqual(originalError.message, '/non-existing-url/value');
     }
   });
 });

test-app/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "@tsconfig/ember/tsconfig.json",
   "compilerOptions": {
+    "target": "es2022",
     // The combination of `baseUrl` with `paths` allows Ember's classic package
     // layout, which is not resolvable with the Node resolution algorithm, to
     // work with TypeScript.