feat: by role ts hints (#1596)

* feat: autocomplete

* refactor: cleanup

* chore: fix typos

Author: mdjastrzebski

.vscode/settings.json

@@ -1,3 +1,3 @@
 {
-  "cSpell.words": ["Pressable", "RNTL"]
+  "cSpell.words": ["Pressable", "RNTL", "Uncapitalize"]
 }

src/fire-event.ts

@@ -11,6 +11,7 @@ import { isHostElement } from './helpers/component-tree';
 import { isHostTextInput } from './helpers/host-component-names';
 import { isPointerEventEnabled } from './helpers/pointer-events';
 import { isTextInputEditable } from './helpers/text-input';
+import { StringWithAutocomplete } from './types';
 
 type EventHandler = (...args: unknown[]) => unknown;
 
@@ -105,20 +106,17 @@ function getEventHandlerName(eventName: string) {
   return `on${eventName.charAt(0).toUpperCase()}${eventName.slice(1)}`;
 }
 
-// Allows any string but will provide autocomplete for type T
-type StringWithAutoComplete<T> = T | (string & Record<never, never>);
-
-// String union type of keys of T that start with on, stripped from on
-type OnKeys<T> = keyof {
+// String union type of keys of T that start with on, stripped of 'on'
+type EventNameExtractor<T> = keyof {
   [K in keyof T as K extends `on${infer Rest}` ? Uncapitalize<Rest> : never]: T[K];
 };
 
-type EventName = StringWithAutoComplete<
-  | OnKeys<ViewProps>
-  | OnKeys<TextProps>
-  | OnKeys<TextInputProps>
-  | OnKeys<PressableProps>
-  | OnKeys<ScrollViewProps>
+type EventName = StringWithAutocomplete<
+  | EventNameExtractor<ViewProps>
+  | EventNameExtractor<TextProps>
+  | EventNameExtractor<TextInputProps>
+  | EventNameExtractor<PressableProps>
+  | EventNameExtractor<ScrollViewProps>
 >;
 
 function fireEvent(element: ReactTestInstance, eventName: EventName, ...data: unknown[]) {

src/helpers/__tests__/accessiblity.test.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { View, Text, TextInput, Pressable, Switch, TouchableOpacity } from 'react-native';
 import { render, isHiddenFromAccessibility, isInaccessible, screen } from '../..';
-import { isAccessibilityElement } from '../accessiblity';
+import { isAccessibilityElement } from '../accessibility';
 
 describe('isHiddenFromAccessibility', () => {
   test('returns false for accessible elements', () => {

src/helpers/accessiblity.ts renamed to src/helpers/accessibility.ts

@@ -16,7 +16,7 @@ export const accessibilityStateKeys: (keyof AccessibilityState)[] = [
   'expanded',
 ];
 
-export const accessiblityValueKeys: (keyof AccessibilityValue)[] = ['min', 'max', 'now', 'text'];
+export const accessibilityValueKeys: (keyof AccessibilityValue)[] = ['min', 'max', 'now', 'text'];
 
 export function isHiddenFromAccessibility(
   element: ReactTestInstance | null,

src/helpers/find-all.ts

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { getConfig } from '../config';
-import { isHiddenFromAccessibility } from './accessiblity';
+import { isHiddenFromAccessibility } from './accessibility';
 import { HostTestInstance, isHostElement } from './component-tree';
 
 interface FindAllOptions {

src/helpers/matchers/match-accessibility-state.ts

@@ -1,6 +1,6 @@
 import { AccessibilityState } from 'react-native';
 import { ReactTestInstance } from 'react-test-renderer';
-import { accessibilityStateKeys, getAccessibilityState } from '../accessiblity';
+import { accessibilityStateKeys, getAccessibilityState } from '../accessibility';
 
 // This type is the same as AccessibilityState from `react-native` package
 // It is re-declared here due to issues with migration from `@types/react-native` to

src/helpers/matchers/match-accessibility-value.ts

@@ -1,5 +1,5 @@
 import { ReactTestInstance } from 'react-test-renderer';
-import { getAccessibilityValue } from '../accessiblity';
+import { getAccessibilityValue } from '../accessibility';
 import { TextMatch } from '../../matches';
 import { matchStringProp } from './match-string-prop';
 

src/helpers/matchers/match-label-text.ts

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { matches, TextMatch, TextMatchOptions } from '../../matches';
-import { getAccessibilityLabel, getAccessibilityLabelledBy } from '../accessiblity';
+import { getAccessibilityLabel, getAccessibilityLabelledBy } from '../accessibility';
 import { findAll } from '../find-all';
 import { matchTextContent } from './match-text-content';
 

src/matchers/to-be-busy.tsx

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
-import { isElementBusy } from '../helpers/accessiblity';
+import { isElementBusy } from '../helpers/accessibility';
 import { checkHostElement, formatElement } from './utils';
 
 export function toBeBusy(this: jest.MatcherContext, element: ReactTestInstance) {

src/matchers/to-be-checked.tsx

@@ -4,7 +4,7 @@ import {
   getAccessibilityCheckedState,
   getAccessibilityRole,
   isAccessibilityElement,
-} from '../helpers/accessiblity';
+} from '../helpers/accessibility';
 import { ErrorWithStack } from '../helpers/errors';
 import { checkHostElement, formatElement } from './utils';
 

src/matchers/to-be-collapsed.tsx

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
-import { isElementCollapsed } from '../helpers/accessiblity';
+import { isElementCollapsed } from '../helpers/accessibility';
 import { checkHostElement, formatElement } from './utils';
 
 export function toBeCollapsed(this: jest.MatcherContext, element: ReactTestInstance) {

src/matchers/to-be-expanded.tsx

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
-import { isElementExpanded } from '../helpers/accessiblity';
+import { isElementExpanded } from '../helpers/accessibility';
 import { checkHostElement, formatElement } from './utils';
 
 export function toBeExpanded(this: jest.MatcherContext, element: ReactTestInstance) {

src/matchers/to-be-partially-checked.tsx

@@ -4,7 +4,7 @@ import {
   getAccessibilityCheckedState,
   getAccessibilityRole,
   isAccessibilityElement,
-} from '../helpers/accessiblity';
+} from '../helpers/accessibility';
 import { ErrorWithStack } from '../helpers/errors';
 import { checkHostElement, formatElement } from './utils';
 

src/matchers/to-be-selected.ts

@@ -1,6 +1,6 @@
 import { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
-import { isElementSelected } from '../helpers/accessiblity';
+import { isElementSelected } from '../helpers/accessibility';
 import { checkHostElement, formatElement } from './utils';
 
 export function toBeSelected(this: jest.MatcherContext, element: ReactTestInstance) {

src/matchers/to-be-visible.tsx

@@ -1,7 +1,7 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
 import { StyleSheet } from 'react-native';
-import { isHiddenFromAccessibility } from '../helpers/accessiblity';
+import { isHiddenFromAccessibility } from '../helpers/accessibility';
 import { getHostParent } from '../helpers/component-tree';
 import { isHostModal } from '../helpers/host-component-names';
 import { checkHostElement, formatElement } from './utils';

src/matchers/to-have-accessibility-value.tsx

@@ -1,6 +1,6 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint, stringify } from 'jest-matcher-utils';
-import { getAccessibilityValue } from '../helpers/accessiblity';
+import { getAccessibilityValue } from '../helpers/accessibility';
 import {
   AccessibilityValueMatcher,
   matchAccessibilityValue,

src/matchers/to-have-accessible-name.tsx

@@ -1,6 +1,6 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 import { matcherHint } from 'jest-matcher-utils';
-import { getAccessibleName } from '../helpers/accessiblity';
+import { getAccessibleName } from '../helpers/accessibility';
 import { TextMatch, TextMatchOptions, matches } from '../matches';
 import { checkHostElement, formatMessage } from './utils';
 

src/pure.ts

@@ -7,7 +7,7 @@ export { default as waitForElementToBeRemoved } from './wait-for-element-to-be-r
 export { within, getQueriesForElement } from './within';
 
 export { configure, resetToDefaults } from './config';
-export { isHiddenFromAccessibility, isInaccessible } from './helpers/accessiblity';
+export { isHiddenFromAccessibility, isInaccessible } from './helpers/accessibility';
 export { getDefaultNormalizer } from './matches';
 export { renderHook } from './render-hook';
 export { screen } from './screen';

src/queries/accessibility-state.ts

@@ -1,5 +1,5 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import { accessibilityStateKeys } from '../helpers/accessiblity';
+import { accessibilityStateKeys } from '../helpers/accessibility';
 import { deprecateQueries } from '../helpers/deprecation';
 import { findAll } from '../helpers/find-all';
 import {

src/queries/accessibility-value.ts

@@ -1,5 +1,5 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import { accessiblityValueKeys } from '../helpers/accessiblity';
+import { accessibilityValueKeys } from '../helpers/accessibility';
 import { deprecateQueries } from '../helpers/deprecation';
 import { findAll } from '../helpers/find-all';
 import {
@@ -27,7 +27,7 @@ const queryAllByA11yValue = (
 const formatQueryParams = (matcher: AccessibilityValueMatcher) => {
   const params: string[] = [];
 
-  accessiblityValueKeys.forEach((valueKey) => {
+  accessibilityValueKeys.forEach((valueKey) => {
     if (matcher[valueKey] !== undefined) {
       params.push(`${valueKey} value: ${matcher[valueKey]}`);
     }

src/queries/role.ts

@@ -1,10 +1,11 @@
 import type { ReactTestInstance } from 'react-test-renderer';
+import type { AccessibilityRole, Role } from 'react-native';
 import {
   accessibilityStateKeys,
-  accessiblityValueKeys,
+  accessibilityValueKeys,
   getAccessibilityRole,
   isAccessibilityElement,
-} from '../helpers/accessiblity';
+} from '../helpers/accessibility';
 import { findAll } from '../helpers/find-all';
 import {
   AccessibilityStateMatcher,
@@ -16,6 +17,7 @@ import {
 } from '../helpers/matchers/match-accessibility-value';
 import { matchStringProp } from '../helpers/matchers/match-string-prop';
 import type { TextMatch } from '../matches';
+import { StringWithAutocomplete } from '../types';
 import { getQueriesForElement } from '../within';
 import { makeQueries } from './make-queries';
 import type {
@@ -28,7 +30,9 @@ import type {
 } from './make-queries';
 import { CommonQueryOptions } from './options';
 
-type ByRoleOptions = CommonQueryOptions &
+export type ByRoleMatcher = StringWithAutocomplete<AccessibilityRole | Role> | RegExp;
+
+export type ByRoleOptions = CommonQueryOptions &
   AccessibilityStateMatcher & {
     name?: TextMatch;
     value?: AccessibilityValueMatcher;
@@ -52,7 +56,9 @@ const matchAccessibilityValueIfNeeded = (
   return value != null ? matchAccessibilityValue(node, value) : true;
 };
 
-const queryAllByRole = (instance: ReactTestInstance): QueryAllByQuery<TextMatch, ByRoleOptions> =>
+const queryAllByRole = (
+  instance: ReactTestInstance,
+): QueryAllByQuery<ByRoleMatcher, ByRoleOptions> =>
   function queryAllByRoleFn(role, options) {
     return findAll(
       instance,
@@ -80,7 +86,7 @@ const formatQueryParams = (role: TextMatch, options: ByRoleOptions = {}) => {
     }
   });
 
-  accessiblityValueKeys.forEach((valueKey) => {
+  accessibilityValueKeys.forEach((valueKey) => {
     if (options?.value?.[valueKey] !== undefined) {
       params.push(`${valueKey} value: ${options?.value?.[valueKey]}`);
     }
@@ -102,12 +108,12 @@ const { getBy, getAllBy, queryBy, queryAllBy, findBy, findAllBy } = makeQueries(
 );
 
 export type ByRoleQueries = {
-  getByRole: GetByQuery<TextMatch, ByRoleOptions>;
-  getAllByRole: GetAllByQuery<TextMatch, ByRoleOptions>;
-  queryByRole: QueryByQuery<TextMatch, ByRoleOptions>;
-  queryAllByRole: QueryAllByQuery<TextMatch, ByRoleOptions>;
-  findByRole: FindByQuery<TextMatch, ByRoleOptions>;
-  findAllByRole: FindAllByQuery<TextMatch, ByRoleOptions>;
+  getByRole: GetByQuery<ByRoleMatcher, ByRoleOptions>;
+  getAllByRole: GetAllByQuery<ByRoleMatcher, ByRoleOptions>;
+  queryByRole: QueryByQuery<ByRoleMatcher, ByRoleOptions>;
+  queryAllByRole: QueryAllByQuery<ByRoleMatcher, ByRoleOptions>;
+  findByRole: FindByQuery<ByRoleMatcher, ByRoleOptions>;
+  findAllByRole: FindAllByQuery<ByRoleMatcher, ByRoleOptions>;
 };
 
 export const bindByRoleQueries = (instance: ReactTestInstance): ByRoleQueries => ({

src/types.ts

@@ -0,0 +1,3 @@
+// TS autocomplete trick
+// Ref: https://github.com/microsoft/TypeScript/issues/29729#issuecomment-567871939
+export type StringWithAutocomplete<T> = T | (string & {});