docs

Author: mdjastrzebski

skills/react-native-testing/references/api-reference-v14.md

@@ -326,7 +326,7 @@ Use when `userEvent` doesn't support the event or when triggering events on comp
 
 ```ts
 async function fireEvent(
-  element: TestInstance,
+  instance: TestInstance,
   eventName: string,
   ...data: unknown[]
 ): Promise<void>;
@@ -361,7 +361,7 @@ Available automatically with any `@testing-library/react-native` import. No setu
 | Matcher               | Signature                                                     | Description                 |
 | --------------------- | ------------------------------------------------------------- | --------------------------- |
 | `toHaveTextContent()` | `(text: string \| RegExp, options?: { exact?, normalizer? })` | Text content match          |
-| `toContainElement()`  | `(element: TestInstance \| null)`                             | Contains child element      |
+| `toContainElement()`  | `(instance: TestInstance \| null)`                            | Contains child element      |
 | `toBeEmptyElement()`  | —                                                             | No children or text content |
 
 ### Element State
@@ -430,7 +430,7 @@ Waits until the queried element is removed. Element must be initially present.
 ### `within`
 
 ```ts
-function within(element: TestInstance): Queries;
+function within(instance: TestInstance): Queries;
 ```
 
 Scoped queries on a subtree. Useful for querying within a single `FlatList` item or a specific screen.
@@ -533,7 +533,7 @@ Note: `concurrentRoot` option is removed (always on). `unstable_validateStringsR
 ### `isHiddenFromAccessibility`
 
 ```ts
-function isHiddenFromAccessibility(element: TestInstance | null): boolean;
+function isHiddenFromAccessibility(instance: TestInstance | null): boolean;
 ```
 
 Also available as `isInaccessible()` alias.

src/__tests__/fire-event.test.tsx

@@ -161,7 +161,7 @@ describe('fireEvent.changeText', () => {
     const input = screen.getByTestId('input');
     await fireEvent.changeText(input, 'new text');
     expect(onChangeText).toHaveBeenCalledWith('new text');
-    expect(nativeState.valueForElement.get(input)).toBe('new text');
+    expect(nativeState.valueForInstance.get(input)).toBe('new text');
   });
 
   test('does not fire on non-editable TextInput', async () => {
@@ -170,7 +170,7 @@ describe('fireEvent.changeText', () => {
     const input = screen.getByTestId('input');
     await fireEvent.changeText(input, 'new text');
     expect(onChangeText).not.toHaveBeenCalled();
-    expect(nativeState.valueForElement.get(input)).toBeUndefined();
+    expect(nativeState.valueForInstance.get(input)).toBeUndefined();
   });
 });
 
@@ -286,7 +286,7 @@ describe('fireEvent.scroll', () => {
     const scrollView = screen.getByTestId('scroll');
     await fireEvent.scroll(scrollView, verticalScrollEvent);
     expect(onScroll.mock.calls[0][0]).toMatchObject(verticalScrollEvent);
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 0, y: 200 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 0, y: 200 });
   });
 
   test.each([
@@ -301,7 +301,7 @@ describe('fireEvent.scroll', () => {
     const scrollView = screen.getByTestId('scroll');
     await fireEvent(scrollView, eventName, verticalScrollEvent);
     expect(handler).toHaveBeenCalledWith(verticalScrollEvent);
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 0, y: 200 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 0, y: 200 });
   });
 
   test('without contentOffset scrolls to (0, 0)', async () => {
@@ -316,7 +316,7 @@ describe('fireEvent.scroll', () => {
     expect(onScroll.mock.calls[0][0]).toMatchObject({
       nativeEvent: { contentOffset: { x: 0, y: 0 } },
     });
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 0, y: 0 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 0, y: 0 });
   });
 
   test('with non-finite contentOffset values uses 0', async () => {
@@ -331,7 +331,7 @@ describe('fireEvent.scroll', () => {
       nativeEvent: { contentOffset: { y: Infinity } },
     });
     expect(onScroll).toHaveBeenCalled();
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 0, y: 0 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 0, y: 0 });
   });
 
   test('with horizontal scroll updates native state', async () => {
@@ -344,7 +344,7 @@ describe('fireEvent.scroll', () => {
     const scrollView = screen.getByTestId('scroll');
     await fireEvent.scroll(scrollView, horizontalScrollEvent);
     expect(onScroll.mock.calls[0][0]).toMatchObject(horizontalScrollEvent);
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 50, y: 0 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 50, y: 0 });
   });
 
   test('without contentOffset via fireEvent() does not update native state', async () => {
@@ -357,7 +357,7 @@ describe('fireEvent.scroll', () => {
     const scrollView = screen.getByTestId('scroll');
     await fireEvent(scrollView, 'scroll', { nativeEvent: {} });
     expect(onScroll).toHaveBeenCalled();
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toBeUndefined();
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toBeUndefined();
   });
 
   test('with non-finite x contentOffset value uses 0', async () => {
@@ -372,7 +372,7 @@ describe('fireEvent.scroll', () => {
       nativeEvent: { contentOffset: { x: Infinity } },
     });
     expect(onScroll).toHaveBeenCalled();
-    expect(nativeState.contentOffsetForElement.get(scrollView)).toEqual({ x: 0, y: 0 });
+    expect(nativeState.contentOffsetForInstance.get(scrollView)).toEqual({ x: 0, y: 0 });
   });
 });
 

src/helpers/accessibility.ts

@@ -150,7 +150,8 @@ export function computeAriaModal(instance: TestInstance): boolean | undefined {
 }
 
 export function computeAriaLabel(instance: TestInstance): string | undefined {
-  const labelElementId = instance.props['aria-labelledby'] ?? instance.props.accessibilityLabelledBy;
+  const labelElementId =
+    instance.props['aria-labelledby'] ?? instance.props.accessibilityLabelledBy;
   if (labelElementId) {
     const container = getContainerInstance(instance);
     const labelInstance = findAll(

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

@@ -20,7 +20,10 @@ export interface AccessibilityStateMatcher {
   expanded?: boolean;
 }
 
-export function matchAccessibilityState(instance: TestInstance, matcher: AccessibilityStateMatcher) {
+export function matchAccessibilityState(
+  instance: TestInstance,
+  matcher: AccessibilityStateMatcher,
+) {
   if (matcher.busy !== undefined && matcher.busy !== computeAriaBusy(instance)) {
     return false;
   }

src/matchers/to-be-busy.ts

@@ -6,18 +6,18 @@ import { computeAriaBusy } from '../helpers/accessibility';
 import { formatElement } from '../helpers/format-element';
 import { checkHostElement } from './utils';
 
-export function toBeBusy(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeBusy, this);
+export function toBeBusy(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeBusy, this);
 
   return {
-    pass: computeAriaBusy(element),
+    pass: computeAriaBusy(instance),
     message: () => {
-      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeBusy`, 'element', '');
+      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeBusy`, 'instance', '');
       return [
         matcher,
         '',
-        `Received element is ${this.isNot ? '' : 'not '}busy:`,
-        redent(formatElement(element), 2),
+        `Received instance is ${this.isNot ? '' : 'not '}busy:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };

src/matchers/to-be-checked.ts

@@ -13,35 +13,35 @@ import { formatElement } from '../helpers/format-element';
 import { isHostSwitch } from '../helpers/host-component-names';
 import { checkHostElement } from './utils';
 
-export function toBeChecked(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeChecked, this);
+export function toBeChecked(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeChecked, this);
 
-  if (!isHostSwitch(element) && !isSupportedAccessibilityElement(element)) {
+  if (!isHostSwitch(instance) && !isSupportedAccessibilityElement(instance)) {
     throw new ErrorWithStack(
       `toBeChecked() works only on host "Switch" elements or accessibility elements with "checkbox", "radio" or "switch" role.`,
       toBeChecked,
     );
   }
 
   return {
-    pass: computeAriaChecked(element) === true,
+    pass: computeAriaChecked(instance) === true,
     message: () => {
       const is = this.isNot ? 'is' : 'is not';
       return [
-        matcherHint(`${this.isNot ? '.not' : ''}.toBeChecked`, 'element', ''),
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeChecked`, 'instance', ''),
         '',
-        `Received element ${is} checked:`,
-        redent(formatElement(element), 2),
+        `Received instance ${is} checked:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };
 }
 
-function isSupportedAccessibilityElement(element: TestInstance) {
-  if (!isAccessibilityElement(element)) {
+function isSupportedAccessibilityElement(instance: TestInstance) {
+  if (!isAccessibilityElement(instance)) {
     return false;
   }
 
-  const role = getRole(element);
+  const role = getRole(instance);
   return rolesSupportingCheckedState[role];
 }

src/matchers/to-be-disabled.ts

@@ -6,46 +6,46 @@ import { computeAriaDisabled } from '../helpers/accessibility';
 import { formatElement } from '../helpers/format-element';
 import { checkHostElement } from './utils';
 
-export function toBeDisabled(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeDisabled, this);
+export function toBeDisabled(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeDisabled, this);
 
-  const isDisabled = computeAriaDisabled(element) || isAncestorDisabled(element);
+  const isDisabled = computeAriaDisabled(instance) || isAncestorDisabled(instance);
 
   return {
     pass: isDisabled,
     message: () => {
       const is = this.isNot ? 'is' : 'is not';
       return [
-        matcherHint(`${this.isNot ? '.not' : ''}.toBeDisabled`, 'element', ''),
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeDisabled`, 'instance', ''),
         '',
-        `Received element ${is} disabled:`,
-        redent(formatElement(element), 2),
+        `Received instance ${is} disabled:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };
 }
 
-export function toBeEnabled(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeEnabled, this);
+export function toBeEnabled(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeEnabled, this);
 
-  const isEnabled = !computeAriaDisabled(element) && !isAncestorDisabled(element);
+  const isEnabled = !computeAriaDisabled(instance) && !isAncestorDisabled(instance);
 
   return {
     pass: isEnabled,
     message: () => {
       const is = this.isNot ? 'is' : 'is not';
       return [
-        matcherHint(`${this.isNot ? '.not' : ''}.toBeEnabled`, 'element', ''),
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeEnabled`, 'instance', ''),
         '',
-        `Received element ${is} enabled:`,
-        redent(formatElement(element), 2),
+        `Received instance ${is} enabled:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };
 }
 
-function isAncestorDisabled(element: TestInstance): boolean {
-  const parent = element.parent;
+function isAncestorDisabled(instance: TestInstance): boolean {
+  const parent = instance.parent;
   if (parent == null) {
     return false;
   }

src/matchers/to-be-empty-element.ts

@@ -6,17 +6,17 @@ import { isTestInstance } from '../helpers/component-tree';
 import { formatElementList } from '../helpers/format-element';
 import { checkHostElement } from './utils';
 
-export function toBeEmptyElement(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeEmptyElement, this);
+export function toBeEmptyElement(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeEmptyElement, this);
 
   // TODO check
-  const children = element.children.filter((child) => isTestInstance(child));
+  const children = instance.children.filter((child) => isTestInstance(child));
 
   return {
     pass: children.length === 0,
     message: () => {
       return [
-        matcherHint(`${this.isNot ? '.not' : ''}.toBeEmptyElement`, 'element', ''),
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeEmptyElement`, 'instance', ''),
         '',
         'Received:',
         `${RECEIVED_COLOR(redent(formatElementList(children), 2))}`,

src/matchers/to-be-expanded.ts

@@ -6,35 +6,35 @@ import { computeAriaExpanded } from '../helpers/accessibility';
 import { formatElement } from '../helpers/format-element';
 import { checkHostElement } from './utils';
 
-export function toBeExpanded(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeExpanded, this);
+export function toBeExpanded(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeExpanded, this);
 
   return {
-    pass: computeAriaExpanded(element) === true,
+    pass: computeAriaExpanded(instance) === true,
     message: () => {
-      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeExpanded`, 'element', '');
+      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeExpanded`, 'instance', '');
       return [
         matcher,
         '',
-        `Received element is ${this.isNot ? '' : 'not '}expanded:`,
-        redent(formatElement(element), 2),
+        `Received instance is ${this.isNot ? '' : 'not '}expanded:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };
 }
 
-export function toBeCollapsed(this: jest.MatcherContext, element: TestInstance) {
-  checkHostElement(element, toBeCollapsed, this);
+export function toBeCollapsed(this: jest.MatcherContext, instance: TestInstance) {
+  checkHostElement(instance, toBeCollapsed, this);
 
   return {
-    pass: computeAriaExpanded(element) === false,
+    pass: computeAriaExpanded(instance) === false,
     message: () => {
-      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeCollapsed`, 'element', '');
+      const matcher = matcherHint(`${this.isNot ? '.not' : ''}.toBeCollapsed`, 'instance', '');
       return [
         matcher,
         '',
-        `Received element is ${this.isNot ? '' : 'not '}collapsed:`,
-        redent(formatElement(element), 2),
+        `Received instance is ${this.isNot ? '' : 'not '}collapsed:`,
+        redent(formatElement(instance), 2),
       ].join('\n');
     },
   };

src/matchers/to-be-on-the-screen.ts

@@ -2,34 +2,34 @@ import { matcherHint, RECEIVED_COLOR } from 'jest-matcher-utils';
 import redent from 'redent';
 import type { TestInstance } from 'test-renderer';
 
-import { getContainerElement } from '../helpers/component-tree';
+import { getContainerInstance } from '../helpers/component-tree';
 import { formatElement } from '../helpers/format-element';
 import { screen } from '../screen';
 import { checkHostElement } from './utils';
 
-export function toBeOnTheScreen(this: jest.MatcherContext, element: TestInstance) {
-  if (element !== null || !this.isNot) {
-    checkHostElement(element, toBeOnTheScreen, this);
+export function toBeOnTheScreen(this: jest.MatcherContext, instance: TestInstance) {
+  if (instance !== null || !this.isNot) {
+    checkHostElement(instance, toBeOnTheScreen, this);
   }
 
-  const pass = element === null ? false : screen.container === getContainerElement(element);
+  const pass = instance === null ? false : screen.container === getContainerInstance(instance);
 
   const errorFound = () => {
-    return `expected element tree not to contain element, but found\n${redent(
-      formatElement(element),
+    return `expected instance tree not to contain instance, but found\n${redent(
+      formatElement(instance),
       2,
     )}`;
   };
 
   const errorNotFound = () => {
-    return `element could not be found in the element tree`;
+    return `instance could not be found in the instance tree`;
   };
 
   return {
     pass,
     message: () => {
       return [
-        matcherHint(`${this.isNot ? '.not' : ''}.toBeOnTheScreen`, 'element', ''),
+        matcherHint(`${this.isNot ? '.not' : ''}.toBeOnTheScreen`, 'instance', ''),
         '',
         RECEIVED_COLOR(this.isNot ? errorFound() : errorNotFound()),
       ].join('\n');