feat: add screen API (#994)

* feature: screen

* feature: update docs

* refactor: add flow type

* docs: more

* docs: final tweaks

* test rerender

* code review changes

* alias RenderResult to RenderAPI

Co-authored-by: Michał Pierzchała <[email protected]>

Author: mdjastrzebski

README.md

@@ -102,22 +102,20 @@ flow-typed install react-test-renderer
 ## Example
 
 ```jsx
-import { render, fireEvent } from '@testing-library/react-native';
+import { render, screen, fireEvent } from '@testing-library/react-native';
 import { QuestionsBoard } from '../QuestionsBoard';
 
 test('form submits two answers', () => {
   const allQuestions = ['q1', 'q2'];
   const mockFn = jest.fn();
 
-  const { getAllByLabelText, getByText } = render(
-    <QuestionsBoard questions={allQuestions} onSubmit={mockFn} />
-  );
+  render(<QuestionsBoard questions={allQuestions} onSubmit={mockFn} />);
 
-  const answerInputs = getAllByLabelText('answer input');
+  const answerInputs = screen.getAllByLabelText('answer input');
 
   fireEvent.changeText(answerInputs[0], 'a1');
   fireEvent.changeText(answerInputs[1], 'a2');
-  fireEvent.press(getByText('Submit'));
+  fireEvent.press(screen.getByText('Submit'));
 
   expect(mockFn).toBeCalledWith({
     '1': { q: 'q1', a: 'a1' },

src/__tests__/screen.test.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { View, Text } from 'react-native';
+import { render, screen } from '..';
+
+test('screen has the same queries as render result', () => {
+  const result = render(<Text>Mt. Everest</Text>);
+  expect(screen).toBe(result);
+
+  expect(screen.getByText('Mt. Everest')).toBeTruthy();
+  expect(screen.queryByText('Mt. Everest')).toBeTruthy();
+  expect(screen.getAllByText('Mt. Everest')).toHaveLength(1);
+  expect(screen.queryAllByText('Mt. Everest')).toHaveLength(1);
+});
+
+test('screen holds last render result', () => {
+  render(<Text>Mt. Everest</Text>);
+  render(<Text>Mt. Blanc</Text>);
+  const finalResult = render(<Text>Śnieżka</Text>);
+  expect(screen).toBe(finalResult);
+
+  expect(screen.getByText('Śnieżka')).toBeTruthy();
+  expect(screen.queryByText('Mt. Everest')).toBeFalsy();
+  expect(screen.queryByText('Mt. Blanc')).toBeFalsy();
+});
+
+test('screen works with updating rerender', () => {
+  const result = render(<Text>Mt. Everest</Text>);
+  expect(screen).toBe(result);
+
+  screen.rerender(<Text>Śnieżka</Text>);
+  expect(screen).toBe(result);
+  expect(screen.getByText('Śnieżka')).toBeTruthy();
+});
+
+test('screen works with nested re-mounting rerender', () => {
+  const result = render(
+    <View>
+      <Text>Mt. Everest</Text>
+    </View>
+  );
+  expect(screen).toBe(result);
+
+  screen.rerender(
+    <View>
+      <View>
+        <Text>Śnieżka</Text>
+      </View>
+    </View>
+  );
+  expect(screen).toBe(result);
+  expect(screen.getByText('Śnieżka')).toBeTruthy();
+});
+
+test('screen throws without render', () => {
+  expect(() => screen.container).toThrowError(
+    '`render` method has not been called'
+  );
+  expect(() => screen.debug()).toThrowError(
+    '`render` method has not been called'
+  );
+  expect(() => screen.debug.shallow()).toThrowError(
+    '`render` method has not been called'
+  );
+  expect(() => screen.getByText('Mt. Everest')).toThrowError(
+    '`render` method has not been called'
+  );
+});

src/cleanup.ts

@@ -1,9 +1,11 @@
 import * as React from 'react';
+import { clearRenderResult } from './screen';
 
 type CleanUpFunction = (nextElement?: React.ReactElement<any>) => void;
 let cleanupQueue = new Set<CleanUpFunction>();
 
 export default function cleanup() {
+  clearRenderResult();
   cleanupQueue.forEach((fn) => fn());
   cleanupQueue.clear();
 }

src/pure.ts

@@ -1,12 +1,16 @@
 import act from './act';
 import cleanup from './cleanup';
 import fireEvent from './fireEvent';
-import render from './render';
+import render, { RenderResult } from './render';
 import waitFor from './waitFor';
 import waitForElementToBeRemoved from './waitForElementToBeRemoved';
 import { within, getQueriesForElement } from './within';
 import { getDefaultNormalizer } from './matches';
 import { renderHook } from './renderHook';
+import { screen } from './screen';
+
+export type { RenderResult };
+export type RenderAPI = RenderResult;
 
 export { act };
 export { cleanup };
@@ -17,4 +21,4 @@ export { waitForElementToBeRemoved };
 export { within, getQueriesForElement };
 export { getDefaultNormalizer };
 export { renderHook };
-export type RenderAPI = ReturnType<typeof render>;
+export { screen };

src/render.tsx

@@ -6,6 +6,7 @@ import { addToCleanupQueue } from './cleanup';
 import debugShallow from './helpers/debugShallow';
 import debugDeep from './helpers/debugDeep';
 import { getQueriesForElement } from './within';
+import { setRenderResult } from './screen';
 
 type Options = {
   wrapper?: React.ComponentType<any>;
@@ -15,6 +16,8 @@ type TestRendererOptions = {
   createNodeMock: (element: React.ReactElement) => any;
 };
 
+export type RenderResult = ReturnType<typeof render>;
+
 /**
  * Renders test component deeply using react-test-renderer and exposes helpers
  * to assert on the output.
@@ -40,7 +43,7 @@ export default function render<T>(
 
   addToCleanupQueue(unmount);
 
-  return {
+  const result = {
     ...getQueriesForElement(instance),
     update,
     unmount,
@@ -49,6 +52,9 @@ export default function render<T>(
     toJSON: renderer.toJSON,
     debug: debug(instance, renderer),
   };
+
+  setRenderResult(result);
+  return result;
 }
 
 function renderWithAct(

src/screen.ts

@@ -0,0 +1,108 @@
+import { ReactTestInstance } from 'react-test-renderer';
+import { RenderResult } from './render';
+
+const SCREEN_ERROR = '`render` method has not been called';
+
+const notImplemented = () => {
+  throw new Error(SCREEN_ERROR);
+};
+
+const notImplementedDebug = () => {
+  throw new Error(SCREEN_ERROR);
+};
+notImplementedDebug.shallow = notImplemented;
+
+const defaultScreen: RenderResult = {
+  get container(): ReactTestInstance {
+    throw new Error(SCREEN_ERROR);
+  },
+  debug: notImplementedDebug,
+  update: notImplemented,
+  unmount: notImplemented,
+  rerender: notImplemented,
+  toJSON: notImplemented,
+  getByLabelText: notImplemented,
+  getAllByLabelText: notImplemented,
+  queryByLabelText: notImplemented,
+  queryAllByLabelText: notImplemented,
+  findByLabelText: notImplemented,
+  findAllByLabelText: notImplemented,
+  getByA11yHint: notImplemented,
+  getByHintText: notImplemented,
+  getAllByA11yHint: notImplemented,
+  getAllByHintText: notImplemented,
+  queryByA11yHint: notImplemented,
+  queryByHintText: notImplemented,
+  queryAllByA11yHint: notImplemented,
+  queryAllByHintText: notImplemented,
+  findByA11yHint: notImplemented,
+  findByHintText: notImplemented,
+  findAllByA11yHint: notImplemented,
+  findAllByHintText: notImplemented,
+  getByRole: notImplemented,
+  getAllByRole: notImplemented,
+  queryByRole: notImplemented,
+  queryAllByRole: notImplemented,
+  findByRole: notImplemented,
+  findAllByRole: notImplemented,
+  getByA11yStates: notImplemented,
+  getAllByA11yStates: notImplemented,
+  queryByA11yStates: notImplemented,
+  queryAllByA11yStates: notImplemented,
+  findByA11yStates: notImplemented,
+  findAllByA11yStates: notImplemented,
+  getByA11yState: notImplemented,
+  getAllByA11yState: notImplemented,
+  queryByA11yState: notImplemented,
+  queryAllByA11yState: notImplemented,
+  findByA11yState: notImplemented,
+  findAllByA11yState: notImplemented,
+  getByA11yValue: notImplemented,
+  getAllByA11yValue: notImplemented,
+  queryByA11yValue: notImplemented,
+  queryAllByA11yValue: notImplemented,
+  findByA11yValue: notImplemented,
+  findAllByA11yValue: notImplemented,
+  UNSAFE_getByProps: notImplemented,
+  UNSAFE_getAllByProps: notImplemented,
+  UNSAFE_queryByProps: notImplemented,
+  UNSAFE_queryAllByProps: notImplemented,
+  UNSAFE_getByType: notImplemented,
+  UNSAFE_getAllByType: notImplemented,
+  UNSAFE_queryByType: notImplemented,
+  UNSAFE_queryAllByType: notImplemented,
+  getByPlaceholderText: notImplemented,
+  getAllByPlaceholderText: notImplemented,
+  queryByPlaceholderText: notImplemented,
+  queryAllByPlaceholderText: notImplemented,
+  findByPlaceholderText: notImplemented,
+  findAllByPlaceholderText: notImplemented,
+  getByDisplayValue: notImplemented,
+  getAllByDisplayValue: notImplemented,
+  queryByDisplayValue: notImplemented,
+  queryAllByDisplayValue: notImplemented,
+  findByDisplayValue: notImplemented,
+  findAllByDisplayValue: notImplemented,
+  getByTestId: notImplemented,
+  getAllByTestId: notImplemented,
+  queryByTestId: notImplemented,
+  queryAllByTestId: notImplemented,
+  findByTestId: notImplemented,
+  findAllByTestId: notImplemented,
+  getByText: notImplemented,
+  getAllByText: notImplemented,
+  queryByText: notImplemented,
+  queryAllByText: notImplemented,
+  findByText: notImplemented,
+  findAllByText: notImplemented,
+};
+
+export let screen: RenderResult = defaultScreen;
+
+export function setRenderResult(output: RenderResult) {
+  screen = output;
+}
+
+export function clearRenderResult() {
+  screen = defaultScreen;
+}

typings/index.flow.js

@@ -363,6 +363,8 @@ declare module '@testing-library/react-native' {
     options?: RenderOptions
   ) => RenderAPI;
 
+  declare export var screen: RenderAPI;
+
   declare export var cleanup: () => void;
   declare export var fireEvent: FireEventAPI;