Tree Traversal

/**
 * Represents a node in the rendered component tree
 */
class ReactTestInstance {
  /** The component type or HTML tag name */
  readonly type: any;
  /** Props passed to the component */
  readonly props: object;
  /** Parent test instance, null for root */
  readonly parent: ReactTestInstance | null;
  /** Array of child test instances and text nodes */
  readonly children: Array<ReactTestInstance | string>;
  /** The underlying component instance (for class components) */
  readonly instance: any;
}

/**
 * The component type or HTML tag name
 * - For DOM elements: string (e.g., 'div', 'span')
 * - For React components: the component function/class
 */
readonly type: any;

const component = create(
  <div>
    <MyComponent />
    <span>Text</span>
  </div>
);

const root = component.root;
console.log(root.type); // 'div'

const myComponent = root.findByType(MyComponent);
console.log(myComponent.type === MyComponent); // true

const span = root.findByType('span');
console.log(span.type); // 'span'

/**
 * Props passed to the component
 * - Excludes 'children' prop for consistency
 * - Returns current props for the component
 */
readonly props: object;

const component = create(
  <button className="primary" disabled onClick={() => {}}>
    Click me
  </button>
);

const button = component.root.findByType('button');
console.log(button.props.className); // 'primary'
console.log(button.props.disabled); // true
console.log(typeof button.props.onClick); // 'function'

/**
 * Parent test instance, null for root elements
 */
readonly parent: ReactTestInstance | null;

/**
 * Array of child test instances and text nodes
 * - Test instances for React components and DOM elements
 * - Strings for text nodes
 */
readonly children: Array<ReactTestInstance | string>;

const component = create(
  <div>
    <span>Hello</span>
    World
    <button>Click</button>
  </div>
);

const root = component.root;
console.log(root.children.length); // 3
console.log(root.children[0].type); // 'span' (ReactTestInstance)
console.log(root.children[1]); // 'World' (string)
console.log(root.children[2].type); // 'button' (ReactTestInstance)

/**
 * The underlying component instance
 * - For class components: the component instance
 * - For function components: null
 * - For DOM elements: the mock or actual DOM node
 */
readonly instance: any;

/**
 * Finds a single matching descendant using a predicate function
 * @param predicate - Function that returns true for the target node
 * @returns Single matching ReactTestInstance
 * @throws Error if no matches or multiple matches found
 */
find(predicate: (node: ReactTestInstance) => boolean): ReactTestInstance;

const component = create(
  <div>
    <button id="save">Save</button>
    <button id="cancel">Cancel</button>
  </div>
);

// Find by custom logic
const saveButton = component.root.find(node => 
  node.type === 'button' && node.props.id === 'save'
);

// Find by text content
const cancelButton = component.root.find(node =>
  node.type === 'button' && 
  node.children.includes('Cancel')
);

/**
 * Finds a single descendant by component type or tag name
 * @param type - Component type or HTML tag name to search for
 * @returns Single matching ReactTestInstance
 * @throws Error if no matches or multiple matches found
 */
findByType(type: any): ReactTestInstance;

const component = create(
  <div>
    <MyComponent />
    <button>Click</button>
  </div>
);

// Find React component
const myComponent = component.root.findByType(MyComponent);

// Find DOM element
const button = component.root.findByType('button');

// Will throw if multiple buttons exist
// const button = component.root.findByType('button'); // Error!

/**
 * Finds a single descendant by matching props
 * @param props - Object with props to match (partial matching)
 * @returns Single matching ReactTestInstance
 * @throws Error if no matches or multiple matches found
 */
findByProps(props: object): ReactTestInstance;

const component = create(
  <form>
    <input type="text" name="username" />
    <input type="password" name="password" />
    <button type="submit" disabled>Submit</button>
  </form>
);

// Find by single prop
const usernameInput = component.root.findByProps({ name: 'username' });

// Find by multiple props
const submitButton = component.root.findByProps({ 
  type: 'submit', 
  disabled: true 
});

/**
 * Finds all matching descendants using a predicate function
 * @param predicate - Function that returns true for target nodes
 * @param options - Search options (deep search by default)
 * @returns Array of matching ReactTestInstance objects
 */
findAll(
  predicate: (node: ReactTestInstance) => boolean,
  options?: FindOptions
): Array<ReactTestInstance>;

interface FindOptions {
  /** Whether to search deeply into the tree (default: true) */
  deep?: boolean;
}

const component = create(
  <div>
    <button>Save</button>
    <div>
      <button>Cancel</button>
      <button disabled>Delete</button>
    </div>
  </div>
);

// Find all buttons
const allButtons = component.root.findAll(node => node.type === 'button');
console.log(allButtons.length); // 3

// Find only direct children (shallow search)
const directChildren = component.root.findAll(
  node => node.type === 'button',
  { deep: false }
);
console.log(directChildren.length); // 1

// Find buttons with specific attributes
const enabledButtons = component.root.findAll(node =>
  node.type === 'button' && !node.props.disabled
);
console.log(enabledButtons.length); // 2

/**
 * Finds all descendants by component type or tag name
 * @param type - Component type or HTML tag name to search for
 * @param options - Search options (deep search by default)
 * @returns Array of matching ReactTestInstance objects
 */
findAllByType(type: any, options?: FindOptions): Array<ReactTestInstance>;

const component = create(
  <form>
    <input type="text" />
    <div>
      <input type="password" />
      <input type="hidden" value="csrf" />
    </div>
  </form>
);

// Find all input elements
const allInputs = component.root.findAllByType('input');
console.log(allInputs.length); // 3

// Find only direct input children
const directInputs = component.root.findAllByType('input', { deep: false });
console.log(directInputs.length); // 1

// Find all instances of a React component
const allMyComponents = component.root.findAllByType(MyComponent);

/**
 * Finds all descendants by matching props
 * @param props - Object with props to match (partial matching)
 * @param options - Search options (deep search by default)  
 * @returns Array of matching ReactTestInstance objects
 */
findAllByProps(props: object, options?: FindOptions): Array<ReactTestInstance>;

const component = create(
  <div>
    <button type="button" className="btn">Save</button>
    <button type="button" className="btn secondary">Cancel</button>
    <button type="submit" className="btn primary">Submit</button>
  </div>
);

// Find all buttons with specific type
const typeButtons = component.root.findAllByProps({ type: 'button' });
console.log(typeButtons.length); // 2

// Find all elements with specific class (partial match)
const btnElements = component.root.findAllByProps({ className: 'btn' });
console.log(btnElements.length); // 3 (partial matching)

// Find with multiple props
const primaryButtons = component.root.findAllByProps({ 
  type: 'submit',
  className: 'btn primary' 
});
console.log(primaryButtons.length); // 1

/**
 * Function type for search predicates
 * @param node - ReactTestInstance to test
 * @returns true if node matches, false otherwise
 */
type Predicate = (node: ReactTestInstance) => boolean | null;

/**
 * Options for controlling search behavior
 */
interface FindOptions {
  /** Whether to search deeply into the tree (default: true) */
  deep?: boolean;
}

// Single find methods throw when no matches found
try {
  component.root.findByType('nonexistent');
} catch (error) {
  console.log(error.message); // "No instances found with node type: "nonexistent""
}

// Single find methods throw when multiple matches found  
try {
  component.root.findByType('button'); // when multiple buttons exist
} catch (error) {
  console.log(error.message); // "Expected 1 but found 3 instances with node type: "button""
}