feat: An HTMLElement can be provided to query functions in order to contain what elements are found.

Searching within an element

Author: prowe

src/happy-path.spec.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { buildQueries, getByRole, render, screen, within } from '@testing-library/react';
 import React, { useEffect, useState } from 'react';
 import { setupMockComponent, getByMockComponent } from './index';
 import { findAllByMockComponent, findByMockComponent, getAllByMockComponent, queryAllByMockComponent, queryByMockComponent } from './queries';
@@ -64,7 +64,7 @@ it('should find via getAllByMockComponent', () => {
     expect(all).toHaveLength(2);
     expect(all[0]).toBeInTheDocument();
     expect(all[1]).toBeInTheDocument();
-    expect(all[0]).not.toBe(all[2]);
+    expect(all[0]).not.toBe(all[1]);
 });
 
 it('should find via queryByMockComponent', () => {
@@ -122,3 +122,114 @@ it('should find via findAllByMockComponent', async () => {
     expect(all[1]).toBeInTheDocument();
     expect(all[0]).not.toBe(all[2]);
 });
+
+describe('Searching within a containing element', () => {
+    it('should find within an element via getByMockComponent', () => {
+        render(
+            <ul>{['A', 'B'].map(value => <li key={value}><MockedComponent value={value} /></li>)}</ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        expect(getByMockComponent(MockedComponent, {container}).props.value).toEqual('A');
+    });
+
+    it('should find within an element via getAllByMockComponent', () => {
+        render(
+            <ul>{['A', 'B'].map(value => 
+                <li key={value}>
+                    <MockedComponent value={value} />
+                    <MockedComponent value={value} />
+                </li>)}
+            </ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        const all = getAllByMockComponent(MockedComponent, {container});
+        expect(all).toHaveLength(2);
+        expect(all[0].props.value).toEqual('A');
+        expect(all[1].props.value).toEqual('A');
+        expect(all[0]).not.toBe(all[1]);
+    });
+
+    it('should find within an element via queryByMockComponent', () => {
+        render(
+            <ul>{['A', 'B'].map(value => 
+                <li key={value}>
+                    <MockedComponent value={value} />
+                </li>)}
+            </ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        expect(queryByMockComponent(MockedComponent, {container})?.props.value).toEqual('A');
+    });
+
+    it('should find within an element via queryAllByMockComponent', () => {
+        render(
+            <ul>{['A', 'B'].map(value => 
+                <li key={value}>
+                    <TestedComponent value={value} />
+                    <TestedComponent value={value} />
+                </li>)}
+            </ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        const all = queryAllByMockComponent(MockedComponent, {container});
+        expect(all).toHaveLength(2);
+        expect(all[0]).toBeInTheDocument();
+        expect(all[1]).toBeInTheDocument();
+        expect(all[0]).not.toBe(all[1]);
+    });
+
+    it('should find within an element via findByMockComponent', async () => {
+        const TimedFunction = () => {
+            const [visible, setVisible] = useState(false);
+            useEffect(() => {
+                const handle = setTimeout(() => setVisible(true), 10);
+                return () => clearTimeout(handle);
+            }, []);
+            return <div>{visible && <MockedComponent value='' />}</div>;
+        };
+        render(
+            <ul>{['A', 'B'].map(value => 
+                <li key={value}>
+                    <TimedFunction />
+                </li>)}
+            </ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        expect(await findByMockComponent(MockedComponent, {container})).toBeInTheDocument();
+    });
+
+    it('should find within an element via findAllByMockComponent', async () => {
+        const TimedFunction = () => {
+            const [visible, setVisible] = useState(false);
+            useEffect(() => {
+                const handle = setTimeout(() => setVisible(true), 10);
+                return () => clearTimeout(handle);
+            }, []);
+            return (
+                <div>
+                    {visible && <span><MockedComponent value='' /><MockedComponent value='' /></span>}
+                </div>
+            );
+        };
+        render(
+            <ul>{['A', 'B'].map(value => 
+                <li key={value}>
+                    <TimedFunction />
+                    <TimedFunction />
+                </li>)}
+            </ul>
+        );
+
+        const container = screen.getAllByRole('listitem')[0];
+        const all = await findAllByMockComponent(MockedComponent, {container});
+        expect(all).toHaveLength(2);
+        expect(all[0]).toBeInTheDocument();
+        expect(all[1]).toBeInTheDocument();
+        expect(all[0]).not.toBe(all[1]);
+    });
+});

src/queries.ts

@@ -1,6 +1,6 @@
 import { FC } from "react";
 import { MockedElement } from "./setupMockComponent";
-import {MatcherFunction, screen} from '@testing-library/react';
+import {MatcherFunction, screen, within} from '@testing-library/react';
 
 function buildMatcherFunctionForComponent<PropType>(mockComponent: FC<PropType>): MatcherFunction {
     return (_, element) => {
@@ -9,44 +9,61 @@ function buildMatcherFunctionForComponent<PropType>(mockComponent: FC<PropType>)
     };
 }
 
+function resolveQueries(options?: QueryOptions) {
+    if (options?.container) {
+        return within(options?.container);
+    }
+    return screen;
+}
+
+/**
+ * A set of options that can be passed to the `*ByMockComponent` functions
+ */
+export interface QueryOptions {
+    /**
+     * If provided, search for mocked components only within this container
+     */
+    container: HTMLElement
+}
+
 /**
  * Attempt to find the mocked element. Throws if not exactly one is found.
  */
-export function getByMockComponent<PropType>(mockComponent: FC<PropType>): MockedElement<PropType> {
-    return screen.getByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function getByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): MockedElement<PropType> {
+    return resolveQueries(options).getByTestId(buildMatcherFunctionForComponent(mockComponent));
 }
 
 /**
  * Attempt to find all mocked elements. Throws if none found.
  */
-export function getAllByMockComponent<PropType>(mockComponent: FC<PropType>): MockedElement<PropType>[] {
-    return screen.getAllByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function getAllByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): MockedElement<PropType>[] {
+    return resolveQueries(options).getAllByTestId(buildMatcherFunctionForComponent(mockComponent));
 }
 
 /**
  * Attempt to find the mocked element. Returns null if not found. Throws if multiple found.
  */
-export function queryByMockComponent<PropType>(mockComponent: FC<PropType>): MockedElement<PropType> | null {
-    return screen.queryByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function queryByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): MockedElement<PropType> | null {
+    return resolveQueries(options).queryByTestId(buildMatcherFunctionForComponent(mockComponent));
 }
 
 /**
  * Attempt to find all mocked element. Returns empty array if not found.
  */
-export function queryAllByMockComponent<PropType>(mockComponent: FC<PropType>): MockedElement<PropType>[] {
-    return screen.queryAllByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function queryAllByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): MockedElement<PropType>[] {
+    return resolveQueries(options).queryAllByTestId(buildMatcherFunctionForComponent(mockComponent));
 }
 
 /**
  * Attempt to find the mocked element. Reject if not eventually found or multiple are found.
  */
-export function findByMockComponent<PropType>(mockComponent: FC<PropType>): Promise<MockedElement<PropType>> {
-    return screen.findByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function findByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): Promise<MockedElement<PropType>> {
+    return resolveQueries(options).findByTestId(buildMatcherFunctionForComponent(mockComponent));
 }
 
 /**
  * Attempt to find all the mocked element. Rejects if non are eventually found.
  */
-export function findAllByMockComponent<PropType>(mockComponent: FC<PropType>): Promise<MockedElement<PropType>[]> {
-    return screen.findAllByTestId(buildMatcherFunctionForComponent(mockComponent));
+export function findAllByMockComponent<PropType>(mockComponent: FC<PropType>, options?: QueryOptions): Promise<MockedElement<PropType>[]> {
+    return resolveQueries(options).findAllByTestId(buildMatcherFunctionForComponent(mockComponent));
 }