Scoped Queries (within)

function within<QueriesToBind extends Queries = typeof queries>(
  element: HTMLElement,
  queriesToBind?: QueriesToBind
): BoundFunctions<QueriesToBind>;

// Alias
function getQueriesForElement(...): BoundFunctions;

import {screen, within} from '@testing-library/dom';

// Find container
const navigation = screen.getByRole('navigation');

// Query within container
const homeLink = within(navigation).getByRole('link', {name: /home/i});
const aboutLink = within(navigation).getByRole('link', {name: /about/i});

// Works with all query variants
const form = screen.getByRole('form');
const email = within(form).getByLabelText('Email');
const password = within(form).getByLabelText('Password');
const submitButton = within(form).getByRole('button', {name: /submit/i});

const todoList = screen.getByRole('list');
const items = within(todoList).getAllByRole('listitem');

// Query within first item
const firstItem = items[0];
const firstCheckbox = within(firstItem).getByRole('checkbox');
const firstDelete = within(firstItem).getByRole('button', {name: /delete/i});

// Open modal
fireEvent.click(screen.getByRole('button', {name: /open/i}));

// Query within modal only
const modal = screen.getByRole('dialog');
const closeButton = within(modal).getByRole('button', {name: /close/i});
const saveButton = within(modal).getByRole('button', {name: /save/i});

import {within, buildQueries} from '@testing-library/dom';

// Define custom query
const [
  queryByDataCy,
  getAllByDataCy,
  getByDataCy,
  findAllByDataCy,
  findByDataCy,
] = buildQueries(
  (container, id) => container.querySelectorAll(`[data-cy="${id}"]`),
  (c, id) => `Found multiple with data-cy="${id}"`,
  (c, id) => `Unable to find with data-cy="${id}"`
);

const customQueries = {
  queryByDataCy, getAllByDataCy, getByDataCy,
  findAllByDataCy, findByDataCy
};

// Use with within
const container = screen.getByTestId('container');
const element = within(container, customQueries).getByDataCy('submit');