diff --git a/README.md b/README.md index cf790132..57fe9766 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,7 @@ when a real user uses it. * [`getByPlaceholderText(container: HTMLElement, text: TextMatch): HTMLElement`](#getbyplaceholdertextcontainer-htmlelement-text-textmatch-htmlelement) * [`getByText(container: HTMLElement, text: TextMatch): HTMLElement`](#getbytextcontainer-htmlelement-text-textmatch-htmlelement) * [`getByAltText(container: HTMLElement, text: TextMatch): HTMLElement`](#getbyalttextcontainer-htmlelement-text-textmatch-htmlelement) + * [`getByTitle(container: HTMLElement, title: ExactTextMatch): HTMLElement`](#getbytitlecontainer-htmlelement-title-exacttextmatch-htmlelement) * [`getByTestId(container: HTMLElement, text: ExactTextMatch): HTMLElement`](#getbytestidcontainer-htmlelement-text-exacttextmatch-htmlelement) * [`wait`](#wait) * [`waitForElement`](#waitforelement) @@ -250,6 +251,15 @@ and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area) const incrediblesPosterImg = getByAltText(container, /incredibles.*poster$/i) ``` +### `getByTitle(container: HTMLElement, title: ExactTextMatch): HTMLElement` + +This will return the element that has the matching `title` attribute. + +```javascript +// +const deleteElement = getByTitle(container, 'Delete') +``` + ### `getByTestId(container: HTMLElement, text: ExactTextMatch): HTMLElement` A shortcut to `` container.querySelector(`[data-testid="${yourId}"]`) `` (and it diff --git a/src/__tests__/__snapshots__/element-queries.js.snap b/src/__tests__/__snapshots__/element-queries.js.snap index a026cde0..67c2c6a9 100644 --- a/src/__tests__/__snapshots__/element-queries.js.snap +++ b/src/__tests__/__snapshots__/element-queries.js.snap @@ -40,6 +40,14 @@ exports[`get throws a useful error message 5`] = ` " `; +exports[`get throws a useful error message 6`] = ` +"Unable to find an element with the title: LucyRicardo. + +
 + 
 +
" +`; + exports[`label with no form control 1`] = ` "Found a label with the text of: alone, however no form control was found associated to that label. Make sure you're using the \\"for\\" attribute or \\"aria-labelledby\\" attribute correctly. diff --git a/src/__tests__/element-queries.js b/src/__tests__/element-queries.js index 2d646d77..ae00396f 100644 --- a/src/__tests__/element-queries.js +++ b/src/__tests__/element-queries.js @@ -23,6 +23,7 @@ test('get throws a useful error message', () => { getByText, getByTestId, getByAltText, + getByTitle, } = render('
') expect(() => getByLabelText('LucyRicardo')).toThrowErrorMatchingSnapshot() expect(() => @@ -31,6 +32,7 @@ test('get throws a useful error message', () => { expect(() => getByText('LucyRicardo')).toThrowErrorMatchingSnapshot() expect(() => getByTestId('LucyRicardo')).toThrowErrorMatchingSnapshot() expect(() => getByAltText('LucyRicardo')).toThrowErrorMatchingSnapshot() + expect(() => getByTitle('LucyRicardo')).toThrowErrorMatchingSnapshot() }) test('can get elements by matching their text content', () => { @@ -117,6 +119,19 @@ test('get element by its alt text', () => { expect(getByAltText(/fin.*nem.*poster$/i).src).toBe('/finding-nemo.png') }) +test('query/get element by its title', () => { + const {getByTitle, queryByTitle} = render(` +
+ + + +
+ `) + + expect(getByTitle('Delete').id).toEqual('2') + expect(queryByTitle('Delete').id).toEqual('2') +}) + test('can get elements by data-testid attribute', () => { const {queryByTestId} = render(`
`) expect(queryByTestId('firstName')).toBeInTheDOM() diff --git a/src/queries.js b/src/queries.js index 97b035f7..7e666549 100644 --- a/src/queries.js +++ b/src/queries.js @@ -68,6 +68,28 @@ function queryByText(container, text, opts) { return firstResultOrNull(queryAllByText, container, text, opts) } +const queryAllByTitle = (...args) => + queryAllByAttribute('title', ...args, {exact: true}) + +const queryByTitle = (...args) => + queryByAttribute('title', ...args, {exact: true}) + +function getAllByTitle(container, title, ...rest) { + const els = queryAllByTitle(container, title, ...rest) + if (!els.length) { + throw new Error( + `Unable to find an element with the title: ${title}. \n\n${debugDOM( + container, + )}`, + ) + } + return els +} + +function getByTitle(...args) { + return firstResultOrNull(getAllByTitle, ...args) +} + // this is just a utility and not an exposed query. // There are no plans to expose this. function queryAllByAttribute(attribute, container, text, {exact = false} = {}) { @@ -215,6 +237,10 @@ export { queryAllByTestId, getByTestId, getAllByTestId, + queryByTitle, + queryAllByTitle, + getByTitle, + getAllByTitle, } /* eslint complexity:["error", 14] */