docs: add comments

Author: mdjastrzebski

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

@@ -1,7 +1,37 @@
+/**
+ * ========================================
+ * React Native Testing Library Tutorial
+ * Chapter 4: Testing Events
+ * ========================================
+ *
+ * This chapter covers how to simulate and test user interactions in React Native
+ * applications using React Native Testing Library's userEvent API.
+ *
+ * Key concepts covered:
+ * - Setting up userEvent for realistic user interactions
+ * - Testing button press events
+ * - Testing text input events
+ * - Testing form submissions
+ * - Testing state changes triggered by events
+ * - Best practices for event testing
+ *
+ * Note: This example uses React Strict DOM (react-strict-dom) which provides
+ * HTML-like components that work across React Native and web platforms.
+ */
+
 import * as React from 'react';
 import { html } from 'react-strict-dom';
 import { render, screen, userEvent } from '@testing-library/react-native';
 
+/**
+ * ========================================
+ * Example 1: Basic Button Press Events
+ * ========================================
+ *
+ * This example demonstrates how to test button press events that trigger
+ * state changes in a component.
+ */
+
 function Counter() {
   const [count, setCount] = React.useState(0);
 
@@ -15,19 +45,53 @@ function Counter() {
   );
 }
 
+/**
+ * Testing button press events:
+ *
+ * 1. Setup userEvent - creates a user session for realistic interactions
+ * 2. Find the button element using queries
+ * 3. Simulate the press event using user.press()
+ * 4. Assert the expected state change occurred
+ *
+ * Key points:
+ * - userEvent.setup() creates a user session for the test
+ * - user.press() simulates a realistic button press (including focus, press, release)
+ * - Always use await when calling userEvent methods (they return promises)
+ * - Test both the initial state and the state after the event
+ */
 test('Counter should increment the count when the button is pressed', async () => {
+  // Setup userEvent - this creates a user session for the test
   const user = userEvent.setup();
 
+  // Render the component
   render(<Counter />);
+
+  // Verify initial state
   expect(screen.getByText('0')).toBeOnTheScreen();
 
+  // Find the button element using role and accessible name
   const button = screen.getByRole('button', { name: 'Increment' });
   expect(button).toBeOnTheScreen();
 
+  // Simulate a button press event
   await user.press(button);
+
+  // Verify the state change occurred
   expect(screen.getByText('1')).toBeOnTheScreen();
 });
 
+/**
+ * ========================================
+ * Example 2: Text Input and Form Events
+ * ========================================
+ *
+ * This example demonstrates testing more complex user interactions including:
+ * - Text input events
+ * - Form submission events
+ * - Conditional rendering based on events
+ * - Error handling scenarios
+ */
+
 function LoginForm() {
   const [email, setEmail] = React.useState('');
   const [password, setPassword] = React.useState('');
@@ -69,24 +133,90 @@ function LoginForm() {
   );
 }
 
+/**
+ * Testing text input events and successful form submission:
+ *
+ * This test demonstrates:
+ * - Using user.type() to simulate realistic text input
+ * - Finding input elements by placeholder text
+ * - Testing form submission with valid data
+ * - Verifying conditional rendering after successful submission
+ *
+ * Key points:
+ * - user.type() simulates realistic typing (including focus, keystrokes, blur)
+ * - Always await user.type() calls
+ * - Use placeholder text, labels, or roles to find input elements
+ * - Test the complete user flow from input to submission to result
+ */
 test('should login with valid credentials', async () => {
   const user = userEvent.setup();
   render(<LoginForm />);
 
+  // Simulate typing in the email field
   await user.type(screen.getByPlaceholderText('Email'), 'test@test.com');
+
+  // Simulate typing in the password field
   await user.type(screen.getByPlaceholderText('Password'), 'password');
+
+  // Simulate clicking the login button
   await user.press(screen.getByRole('button', { name: 'Login' }));
 
+  // Verify successful login redirects to success page
   expect(screen.getByRole('heading', { name: 'Login successful' })).toBeOnTheScreen();
 });
 
+/**
+ * Testing error scenarios:
+ *
+ * This test demonstrates:
+ * - Testing error handling with invalid inputs
+ * - Verifying error messages are displayed correctly
+ * - Using role="alert" for error messages (accessibility best practice)
+ *
+ * Key points:
+ * - Always test both success and error scenarios
+ * - Use role="alert" for error messages to ensure accessibility
+ * - Test that error messages have appropriate accessible names
+ * - Verify error states don't accidentally trigger success states
+ */
 test('should show error message with invalid credentials', async () => {
   const user = userEvent.setup();
   render(<LoginForm />);
 
+  // Enter valid email but invalid password
   await user.type(screen.getByPlaceholderText('Email'), 'test@test.com');
   await user.type(screen.getByPlaceholderText('Password'), 'wrong-password');
+
+  // Attempt to login
   await user.press(screen.getByRole('button', { name: 'Login' }));
 
+  // Verify error message is displayed
   expect(screen.getByRole('alert', { name: 'Invalid credentials' })).toBeOnTheScreen();
 });
+
+/**
+ * ========================================
+ * Best Practices for Event Testing
+ * ========================================
+ *
+ * 1. Always use userEvent.setup() to create a user session
+ * 2. Always await userEvent method calls (they return promises)
+ * 3. Use realistic user interactions (user.press, user.type) over fireEvent
+ * 4. Test both success and error scenarios
+ * 5. Find elements using accessible queries (role, label, placeholder)
+ * 6. Test the complete user flow, not just individual events
+ * 7. Verify state changes and side effects after events
+ * 8. Use role="alert" for error messages and test them appropriately
+ *
+ * ========================================
+ * Common userEvent Methods
+ * ========================================
+ *
+ * - user.press(element) - Simulates pressing a button or touchable element
+ * - user.type(element, text) - Simulates typing text into an input
+ * - user.clear(element) - Clears text from an input
+ * - user.selectText(element, options) - Selects text in an input
+ * - user.scroll(element, options) - Simulates scrolling gestures
+ *
+ * For more advanced event testing, see the userEvent documentation.
+ */

examples/cookbook/basics-tutorial/1-basics.test.tsx

@@ -1,7 +1,31 @@
+/*
+ * React Native Testing Library - Chapter 1: Basics
+ *
+ * This tutorial introduces the fundamentals of testing React Native components
+ * using React Native Testing Library (RNTL). You'll learn how to render components,
+ * query elements, and write basic assertions.
+ *
+ * What is React Native Testing Library?
+ * - A testing utility that helps you test React Native components in a way that
+ *   resembles how your users interact with your app
+ * - Built on top of Jest and React Test Renderer
+ * - Encourages testing behavior rather than implementation details
+ */
+
 import * as React from 'react';
 import { Text, View } from 'react-native';
+
+// Import the essential testing utilities from React Native Testing Library
 import { render, screen } from '@testing-library/react-native';
+// - render: Creates a virtual representation of your component for testing
+// - screen: Provides convenient methods to query rendered elements
 
+/*
+ * Example Component: Greeting
+ *
+ * This is a simple React Native component that we'll use to demonstrate
+ * basic testing concepts. It renders a greeting message with an optional name.
+ */
 function Greeting({ name = 'World' }) {
   return (
     <View>
@@ -10,20 +34,43 @@ function Greeting({ name = 'World' }) {
   );
 }
 
+/*
+ * Test Suite: Greeting Component
+ *
+ * A test suite groups related tests together. We use Jest's describe() function
+ * to create a test suite for our Greeting component.
+ */
 describe('Greeting', () => {
+  /*
+   * Test Case 1: Basic Rendering
+   *
+   * This test verifies that our component renders correctly with default props.
+   * It follows the Arrange-Act-Assert pattern (though "Act" is implicit in the render).
+   */
   it('should render', () => {
-    // Arrange
+    // Arrange: Set up the test by rendering the component
+    // The render() function creates a virtual DOM representation of your component
     render(<Greeting />);
 
-    // Assert`
+    // Assert: Verify the expected behavior
+    // screen.getByText() queries for an element containing the specified text
+    // toBeOnTheScreen() is a custom matcher that checks if the element is rendered
     expect(screen.getByText('Hello, World!')).toBeOnTheScreen();
   });
 
+  /*
+   * Test Case 2: Testing with Props
+   *
+   * This test demonstrates how to test component behavior when props change.
+   * It shows how the same component can render differently based on input.
+   */
   it('should render with the correct name', () => {
-    // Arrange
+    // Arrange: Render the component with specific props
+    // We're passing a custom name prop to test dynamic content
     render(<Greeting name="John" />);
 
-    // Assert
+    // Assert: Verify that the component renders with the provided prop
+    // The text should now include "John" instead of the default "World"
     expect(screen.getByText('Hello, John!')).toBeOnTheScreen();
   });
 });

examples/cookbook/basics-tutorial/2.1-query-variants.test.tsx

@@ -1,29 +1,65 @@
+/**
+ * React Native Testing Library Tutorial - Chapter 2.1: Query Variants
+ *
+ * This tutorial demonstrates the three main query variants in React Native Testing Library:
+ * - getBy*: Finds a single element, throws error if not found or multiple found
+ * - queryBy*: Finds a single element, returns null if not found (no error)
+ * - findBy*: Async version of getBy*, waits for element to appear
+ *
+ * Each variant also has an "All" version (getAllBy*, queryAllBy*, findAllBy*)
+ * that returns arrays of elements instead of single elements.
+ */
+
 import * as React from 'react';
 import { Text, View } from 'react-native';
 import { render, screen } from '@testing-library/react-native';
 
+/**
+ * TEST 1: Basic Query Variants
+ *
+ * This test demonstrates the fundamental differences between getBy*, getAllBy*,
+ * and queryBy* queries for synchronous DOM queries.
+ */
 test('showcase query variants', () => {
+  // Render a simple component with multiple text elements
   render(
     <View>
       <Text>Item 1</Text>
       <Text>Item 2</Text>
     </View>,
   );
 
-  // Use getBy* queries to find a single element matching given predicate
+  // ✅ getBy* queries: Use when you expect exactly ONE element to be found
+  // - Throws an error if the element is not found
+  // - Throws an error if multiple elements are found
+  // - Perfect for assertions where the element MUST exist
   expect(screen.getByText('Item 1')).toBeOnTheScreen();
 
-  // Use getAllBy* queries to find all elements matching given predicate (note the use of a regex)
+  // ✅ getAllBy* queries: Use when you expect MULTIPLE elements to be found
+  // - Returns an array of all matching elements
+  // - Throws an error if NO elements are found
+  // - Perfect for testing multiple matching elements
   expect(screen.getAllByText(/Item/)).toHaveLength(2);
 
-  // Use queryBy* to look for an element that you expect does not exist
+  // ✅ queryBy* queries: Use when you expect an element to NOT exist
+  // - Returns null if the element is not found (no error thrown)
+  // - Returns the element if found (like getBy*)
+  // - Perfect for testing absence of elements
   expect(screen.queryByText('Item 3')).not.toBeOnTheScreen();
 });
 
+/**
+ * LazyText Component - Simulates Async Loading
+ *
+ * This component demonstrates a common pattern in React Native apps:
+ * - Initially shows a loading state
+ * - After async operation completes, shows the actual content
+ * - Useful for testing async query variants
+ */
 function LazyText({ content }: { content: string }) {
   const [isLoaded, setIsLoaded] = React.useState(false);
 
-  // Simulate async loading operation
+  // Simulate async loading operation (API call, data fetching, etc.)
   React.useEffect(() => {
     sleep(100);
     setIsLoaded(true);
@@ -32,19 +68,56 @@ function LazyText({ content }: { content: string }) {
   return <Text>{isLoaded ? content : 'Loading...'}</Text>;
 }
 
+/**
+ * TEST 2: Async Query Variants
+ *
+ * This test demonstrates findBy* queries, which are essential for testing
+ * components that load content asynchronously.
+ */
 test('showcase async query variants', async () => {
+  // Render components that will load content asynchronously
   render(
     <View>
       <LazyText content="Lazy Item 1" />
       <LazyText content="Lazy Item 2" />
     </View>,
   );
 
-  // Use findBy* to wait for an element to appear
+  // ✅ findBy* queries: Use when you need to WAIT for an element to appear
+  // - Returns a Promise that resolves when the element is found
+  // - Automatically retries until element appears (with timeout)
+  // - Perfect for async operations like API calls, animations, etc.
+  // - Default timeout is 1000ms (configurable)
   expect(await screen.findByText('Lazy Item 1')).toBeOnTheScreen();
+
+  // ❌ DON'T use getBy* for async content - this would fail:
+  // expect(screen.getByText('Lazy Item 1')).toBeOnTheScreen(); // Error!
+
+  // ❌ DON'T use queryBy* for async content - this would return null:
+  // expect(screen.queryByText('Lazy Item 1')).toBeOnTheScreen(); // Fails!
 });
 
-// Simulate async operation
+/**
+ * Query Variants Summary:
+ *
+ * +----------+------------+------------+------------+
+ * | Variant  | Single     | Multiple   | Use Case   |
+ * +----------+------------+------------+------------+
+ * | getBy*   | getByText  | getAllBy*  | Element must exist (sync) |
+ * | queryBy* | queryByText| queryAllBy*| Element may not exist |
+ * | findBy*  | findByText | findAllBy* | Element appears async |
+ * +----------+------------+------------+------------+
+ *
+ * When to use each:
+ * - getBy*: "I know this element exists right now"
+ * - queryBy*: "This element might not exist, and that's okay"
+ * - findBy*: "This element will exist soon (after async operation)"
+ */
+
+/**
+ * Utility function to simulate async operations
+ * In real apps, this might be API calls, database queries, etc.
+ */
 function sleep(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }