fix: log correct docs link for invalid key descriptors (#881)

Author: ph-fritsche

src/keyboard/parseKeyDef.ts

@@ -27,7 +27,7 @@ export function parseKeyDef(keyboardMap: keyboardKey[], text: string) {
       releasePrevious,
       releaseSelf = true,
       repeat,
-    } = readNextDescriptor(text)
+    } = readNextDescriptor(text, 'keyboard')
 
     const keyDef = keyboardMap.find(def => {
       if (type === '[') {

src/pointer/parseKeyDef.ts

@@ -14,7 +14,7 @@ export function parseKeyDef(pointerMap: pointerKey[], keys: string) {
       consumedLength,
       releasePrevious,
       releaseSelf = true,
-    } = readNextDescriptor(keys)
+    } = readNextDescriptor(keys, 'pointer')
     const keyDef = pointerMap.find(p => p.name === descriptor)
 
     if (keyDef) {

src/utils/keyDef/readNextDescriptor.ts

@@ -3,6 +3,8 @@ enum bracketDict {
   '[' = ']',
 }
 
+type Context = 'pointer' | 'keyboard'
+
 /**
  * Read the next key definition from user input
  *
@@ -14,7 +16,7 @@ enum bracketDict {
  * When keeping the key pressed you can choose how long the key is pressed `{descriptor>3}`.
  * You can then release the key per `{descriptor>3/}` or keep it pressed and continue with the next key.
  */
-export function readNextDescriptor(text: string) {
+export function readNextDescriptor(text: string, context: Context) {
   let pos = 0
   const startBracket =
     text[pos] in bracketDict ? (text[pos] as keyof typeof bracketDict) : ''
@@ -27,14 +29,16 @@ export function readNextDescriptor(text: string) {
 
   return {
     type,
-    ...(type === '' ? readPrintableChar(text, pos) : readTag(text, pos, type)),
+    ...(type === ''
+      ? readPrintableChar(text, pos, context)
+      : readTag(text, pos, type, context)),
   }
 }
 
-function readPrintableChar(text: string, pos: number) {
+function readPrintableChar(text: string, pos: number, context: Context) {
   const descriptor = text[pos]
 
-  assertDescriptor(descriptor, text, pos)
+  assertDescriptor(descriptor, text, pos, context)
 
   pos += descriptor.length
 
@@ -51,6 +55,7 @@ function readTag(
   text: string,
   pos: number,
   startBracket: keyof typeof bracketDict,
+  context: Context,
 ) {
   const releasePreviousModifier = text[pos] === '/' ? '/' : ''
 
@@ -64,7 +69,7 @@ function readTag(
     ? text[pos]
     : text.slice(pos).match(startBracket === '{' ? /^\w+|^[^}>/]/ : /^\w+/)?.[0]
 
-  assertDescriptor(descriptor, text, pos)
+  assertDescriptor(descriptor, text, pos, context)
 
   pos += descriptor.length
 
@@ -92,6 +97,7 @@ function readTag(
           .join(' or '),
         text[pos],
         text,
+        context,
       ),
     )
   }
@@ -111,9 +117,10 @@ function assertDescriptor(
   descriptor: string | undefined,
   text: string,
   pos: number,
+  context: Context,
 ): asserts descriptor is string {
   if (!descriptor) {
-    throw new Error(getErrorMessage('key descriptor', text[pos], text))
+    throw new Error(getErrorMessage('key descriptor', text[pos], text, context))
   }
 }
 
@@ -131,8 +138,13 @@ function getErrorMessage(
   expected: string,
   found: string | undefined,
   text: string,
+  context: Context,
 ) {
   return `Expected ${expected} but found "${found ?? ''}" in "${text}"
-    See https://github.com/testing-library/user-event/blob/main/README.md#keyboardtext-options
+    See ${
+      context === 'pointer'
+        ? `https://testing-library.com/docs/user-event/pointer#pressing-a-button-or-touching-the-screen`
+        : `https://testing-library.com/docs/user-event/keyboard`
+    }
     for more information about how userEvent parses your input.`
 }

tests/keyboard/parseKeyDef.ts

@@ -110,32 +110,3 @@ cases(
     },
   },
 )
-
-cases(
-  'errors',
-  ({text, expectedError}) => {
-    expect(() => parseKeyDef(defaultKeyMap, `${text}`)).toThrow(expectedError)
-  },
-  {
-    'missing descriptor': {
-      text: '',
-      expectedError: 'but found "" in ""',
-    },
-    'missing closing bracket': {
-      text: '{a)',
-      expectedError: 'but found ")" in "{a)"',
-    },
-    'invalid repeat modifier': {
-      text: '{a>e}',
-      expectedError: 'but found "e" in "{a>e}"',
-    },
-    'missing bracket after repeat modifier': {
-      text: '{a>3)',
-      expectedError: 'but found ")" in "{a>3)"',
-    },
-    'unescaped modifier': {
-      text: '{/>5}',
-      expectedError: 'but found ">" in "{/>5}"',
-    },
-  },
-)

tests/utils/keyDef/readNextDescriptor.ts

@@ -0,0 +1,43 @@
+import cases from 'jest-in-case'
+import {readNextDescriptor} from '#src/utils'
+import userEvent from '#src'
+
+cases(
+  'errors',
+  ({text, expectedError}) => {
+    expect(() => readNextDescriptor(`${text}`, 'keyboard')).toThrow(
+      expectedError,
+    )
+  },
+  {
+    'missing descriptor': {
+      text: '',
+      expectedError: 'but found "" in ""',
+    },
+    'missing closing bracket': {
+      text: '{a)',
+      expectedError: 'but found ")" in "{a)"',
+    },
+    'invalid repeat modifier': {
+      text: '{a>e}',
+      expectedError: 'but found "e" in "{a>e}"',
+    },
+    'missing bracket after repeat modifier': {
+      text: '{a>3)',
+      expectedError: 'but found ")" in "{a>3)"',
+    },
+    'unescaped modifier': {
+      text: '{/>5}',
+      expectedError: 'but found ">" in "{/>5}"',
+    },
+  },
+)
+
+test('include appropriate docs link in error message', async () => {
+  await expect(() => userEvent.keyboard('{')).rejects.toThrow(
+    'docs/user-event/keyboard',
+  )
+  await expect(() => userEvent.pointer('{')).rejects.toThrow(
+    'docs/user-event/pointer',
+  )
+})