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`] = `
[36m[39m"
`;
+exports[`get throws a useful error message 6`] = `
+"Unable to find an element with the title: LucyRicardo.
+
+[36m
[39m"
+`;
+
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] */