docs: testing basics tutorial (#1789)

Author: mdjastrzebski

examples/basic/jest.config.js

@@ -1,5 +1,8 @@
 module.exports = {
   preset: 'react-native',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(jest-)?react-native|@react-native(-community)?)',
+  ],
   setupFilesAfterEnv: ['./jest-setup.ts'],
 };

examples/basic/package.json

@@ -26,7 +26,7 @@
     "@types/react": "~18.3.12",
     "eslint": "^8.57.0",
     "jest": "^29.7.0",
-    "react-test-renderer": "18.2.0",
+    "react-test-renderer": "18.3.1",
     "typescript": "^5.3.0"
   },
   "private": true,

examples/basic/yarn.lock

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { html } from 'react-strict-dom';
+import { render, screen } from '@testing-library/react-native';
+
+function Greeting({ name = 'World' }) {
+  return (
+    <html.div>
+      <html.span>Hello, {name}!</html.span>
+    </html.div>
+  );
+}
+
+describe('Greeting', () => {
+  it('should render', () => {
+    // Arrange
+    render(<Greeting />);
+
+    // Assert
+    expect(screen.getByText('Hello, World!')).toBeOnTheScreen();
+  });
+
+  it('should render with the correct name', () => {
+    // Arrange
+    render(<Greeting name="John" />);
+
+    // Assert
+    expect(screen.getByText('Hello, John!')).toBeOnTheScreen();
+  });
+});

examples/cookbook/basics-tutorial-react-strict-dom/1-basics-rsd.test.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { html } from 'react-strict-dom';
+import { render, screen } from '@testing-library/react-native';
+
+test('showcase query variants', () => {
+  render(
+    <html.div>
+      <html.span>Item 1</html.span>
+      <html.span>Item 2</html.span>
+    </html.div>,
+  );
+
+  // Use getBy* queries to find a single element matching given predicate
+  expect(screen.getByText('Item 1')).toBeOnTheScreen();
+
+  // Use getAllBy* queries to find all elements matching given predicate (note the use of a regex)
+  expect(screen.getAllByText(/Item/)).toHaveLength(2);
+
+  // Use queryBy* to look for an element that you expect does not exist
+  expect(screen.queryByText('Item 3')).not.toBeOnTheScreen();
+});
+
+function LazyText({ content }: { content: string }) {
+  const [isLoaded, setIsLoaded] = React.useState(false);
+
+  // Simulate async loading operation
+  React.useEffect(() => {
+    sleep(100);
+    setIsLoaded(true);
+  }, []);
+
+  return <html.span>{isLoaded ? content : 'Loading...'}</html.span>;
+}
+
+test('showcase async query variants', async () => {
+  render(
+    <html.div>
+      <LazyText content="Lazy Item 1" />
+      <LazyText content="Lazy Item 2" />
+    </html.div>,
+  );
+
+  // Use findBy* to wait for an element to appear
+  expect(await screen.findByText('Lazy Item 1')).toBeOnTheScreen();
+});
+
+// Simulate async operation
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

examples/cookbook/basics-tutorial-react-strict-dom/2.1-query-variants-rsd.test.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import { html } from 'react-strict-dom';
+import { render, screen } from '@testing-library/react-native';
+
+test('query by semantic role: *ByRole (highly recommended)', () => {
+  render(
+    <html.div>
+      <html.h1>Heading Text</html.h1>
+
+      <html.button>Button 1</html.button>
+
+      <html.p role="alert">Alert Text</html.p>
+
+      <html.div role="menu">
+        <html.span role="menuitem">Menu Item 1</html.span>
+        <html.span role="menuitem">Menu Item 2</html.span>
+      </html.div>
+    </html.div>,
+  );
+
+  expect(screen.getByRole('heading', { name: 'Heading Text' })).toBeOnTheScreen();
+
+  expect(screen.getByRole('button', { name: 'Button 1' })).toBeOnTheScreen();
+  expect(screen.getByRole('alert', { name: 'Alert Text' })).toBeOnTheScreen();
+
+  // TODO: RSD does not set accessible for role elements.
+  // expect(screen.getByRole('menu')).toBeOnTheScreen();
+  // expect(screen.getAllByRole('menuitem')).toHaveLength(2);
+});
+
+test('querying TextInput elements (recommended)', () => {
+  render(
+    <html.div>
+      <html.input placeholder="Enter Text..." aria-label="Text Label" defaultValue="Hello" />
+    </html.div>,
+  );
+
+  // Option 1: Query by a11y label
+  expect(screen.getByLabelText('Text Label')).toHaveDisplayValue('Hello');
+
+  // Option 2: Query by placeholder text
+  expect(screen.getByPlaceholderText('Enter Text...')).toHaveDisplayValue('Hello');
+
+  // Option 3: Query by display value
+  expect(screen.getByDisplayValue('Hello')).toBeOnTheScreen();
+});
+
+test('other accessible queries (ok)', () => {
+  render(
+    <html.div>
+      <html.span>Text content</html.span>
+      <html.div aria-label="ARIA Label" />
+    </html.div>,
+  );
+
+  expect(screen.getByText('Text content')).toBeOnTheScreen();
+  expect(screen.getByLabelText('ARIA Label')).toBeOnTheScreen();
+});
+
+test('escape hatch: *ByTestId (use as a last resort)', () => {
+  render(
+    <html.div>
+      <html.span data-testid="Text 1">Text 1</html.span>
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('Text 1')).toBeOnTheScreen();
+});

examples/cookbook/basics-tutorial-react-strict-dom/2.2-query-predicates-rsd.test.tsx

@@ -0,0 +1,187 @@
+import * as React from 'react';
+import { render, screen } from '@testing-library/react-native';
+import { html, css } from 'react-strict-dom';
+
+test('showcase: toBeOnTheScreen', () => {
+  render(
+    <html.div>
+      <html.div data-testid="view" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('view')).toBeOnTheScreen();
+  expect(screen.queryByTestId('non-existent')).not.toBeOnTheScreen();
+});
+
+test('showcase: toBeIntoHaveTextContentTheDocument', () => {
+  render(
+    <html.div>
+      <html.p data-testid="text">Hello World</html.p>
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('text')).toHaveTextContent('Hello World');
+  expect(screen.getByTestId('text')).toHaveTextContent(/hello/i);
+  expect(screen.getByTestId('text')).toHaveTextContent('Hello', { exact: false });
+});
+
+test('showcase: toContainElement', () => {
+  render(
+    <html.div>
+      <html.div data-testid="outer">
+        <html.div data-testid="inner" />
+      </html.div>
+      <html.div data-testid="outer-2" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('outer')).toContainElement(screen.getByTestId('inner'));
+  expect(screen.getByTestId('outer')).not.toContainElement(screen.getByTestId('outer-2'));
+});
+
+test('showcase: toBeEmptyElement', () => {
+  render(
+    <html.div>
+      <html.div data-testid="empty" />
+      <html.div data-testid="not-empty">
+        <html.p data-testid="text">Hello World</html.p>
+      </html.div>
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('empty')).toBeEmptyElement();
+  expect(screen.getByTestId('not-empty')).not.toBeEmptyElement();
+});
+
+test('showcase: toHaveDisplayValue', () => {
+  render(
+    <html.div>
+      <html.input data-testid="input" value="Hello" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('input')).toHaveDisplayValue('Hello');
+});
+
+test('showcase: toHaveAccessibilityValue', () => {
+  render(
+    <html.div>
+      <html.div
+        data-testid="view"
+        aria-valuetext="33%"
+        aria-valuenow={33}
+        aria-valuemax={100}
+        aria-valuemin={0}
+      />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('view')).toHaveAccessibilityValue({ text: '33%' });
+  expect(screen.getByTestId('view')).toHaveAccessibilityValue({ now: 33 });
+  expect(screen.getByTestId('view')).toHaveAccessibilityValue({ now: 33, min: 0, max: 100 });
+});
+
+test('showcase: toBeEnabled/toBeDisabled', () => {
+  render(
+    <html.div>
+      <html.div data-testid="enabled" aria-disabled={false} />
+      <html.div data-testid="disabled" aria-disabled />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('enabled')).toBeEnabled();
+  expect(screen.getByTestId('enabled')).not.toBeDisabled();
+  expect(screen.getByTestId('disabled')).toBeDisabled();
+  expect(screen.getByTestId('disabled')).not.toBeEnabled();
+});
+
+test('showcase: toBeSelected', () => {
+  render(
+    <html.div>
+      <html.div data-testid="selected" aria-selected />
+      <html.div data-testid="not-selected" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('selected')).toBeSelected();
+  expect(screen.getByTestId('not-selected')).not.toBeSelected();
+});
+
+test('showcase: toBeBusy', () => {
+  render(
+    <html.div>
+      <html.div data-testid="busy" aria-busy />
+      <html.div data-testid="not-busy" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('busy')).toBeBusy();
+  expect(screen.getByTestId('not-busy')).not.toBeBusy();
+});
+
+test('showcase: toBeExpanded/toBeCollapsed', () => {
+  render(
+    <html.div>
+      <html.div data-testid="expanded" aria-expanded />
+      <html.div data-testid="collapsed" aria-expanded={false} />
+      <html.div data-testid="default" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('expanded')).toBeExpanded();
+  expect(screen.getByTestId('expanded')).not.toBeCollapsed();
+
+  expect(screen.getByTestId('collapsed')).toBeCollapsed();
+  expect(screen.getByTestId('collapsed')).not.toBeExpanded();
+
+  expect(screen.getByTestId('default')).not.toBeCollapsed();
+  expect(screen.getByTestId('default')).not.toBeExpanded();
+});
+
+test('showcase: toBeVisible', () => {
+  render(
+    <html.div>
+      <html.div data-testid="visible" />
+      <html.div data-testid="not-visible" style={styles.opacityZero} />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('visible')).toBeVisible();
+  expect(screen.getByTestId('not-visible')).not.toBeVisible();
+});
+
+test('showcase: toHaveStyle', () => {
+  render(
+    <html.div>
+      <html.span data-testid="text" style={styles.fontSize16}>
+        Hello World
+      </html.span>
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('text')).toHaveStyle({ fontSize: 16 });
+  expect(screen.getByTestId('text')).not.toHaveStyle({ fontSize: 12 });
+});
+
+test('showcase: toHaveProp', () => {
+  render(
+    <html.div>
+      <html.p data-testid="text" aria-label="Hello World" />
+    </html.div>,
+  );
+
+  expect(screen.getByTestId('text')).toHaveProp('accessibilityLabel');
+  expect(screen.getByTestId('text')).not.toHaveProp('aria-hidden');
+
+  expect(screen.getByTestId('text')).toHaveProp('accessibilityLabel', 'Hello World');
+  expect(screen.getByTestId('text')).not.toHaveProp('accessibilityLabel', 'Goodbye World');
+});
+
+const styles = css.create({
+  opacityZero: {
+    opacity: '0%',
+  },
+  fontSize16: {
+    fontSize: '16px',
+  },
+});