What is the name option in react-testing-library?

Question

Ever since starting with @testing-library for react, I'm confused by the name attribute. It is possible to get the reference of a rendered button e. g. like this:

// <button>Button text</button>
screen.getbyRole("button", {name: /button text/gi})

In this case name referes to the textNode inside of the button. The story around inputs is similar where name can refer to e.g. the id the name or the text content.

I'm currently trying to get the reference of a button that is rendered like this:

<button
  aria-label="Close"
  class="css-1dliicy"
  type="button"
  >
  Create new
  <svg>...</svg>
</button>

And the button can not be found with the query:

const createNewButton = screen.getByRole('button', {
    name: /Create new/gi,
});

I clearly don't seem to know what the name property means but I can't seem to find docs on it.

Answer 1

The name property refers to the accessible name of the element you're trying to query.

From the ByRole query docs (third paragraph):

You can query the returned element(s) by their accessible name. The accessible name is for simple cases equal to e.g. the label of a form element, or the text content of a button, or the value of the aria-label attribute. It can be used to query a specific element if multiple elements with the same role are present on the rendered content.

---

As @Moistbobo referred to, since your button has aria-label="Close", then Close will be its accessible name.

Answer 2

The issue here is that the first button doesn't have an aria-label, and by default will fallback to using the button content for accessibility.

As the second button has Close as an aria-label, the name property in this case should be Close.

I've written the following tests to demonstrate this.

import {render} from "@testing-library/react";

describe('test', () => {
   it('find by name -> aria-label', () => {
       const {getByRole} = render(<button
           aria-label="Close"
           className="css-1dliicy"
           type="button"
       >
           Create new
       </button>)

       const button = getByRole('button', {name: 'Close'});

       expect(button).toBeTruthy();
   })

    it('find by name -> button content', () => {
        const {getByRole} = render(
            <button>button text</button>
        );

        const button = getByRole("button", {name: /button text/gi});

        expect(button).toBeTruthy();
    })

    it('will throw an error', () => {
        const {getByRole} = render(
            <button>button text</button>
        );

        /** will throw this error:
         * Unable to find an accessible element with the role "button" and name `/button texat/gi`
         *  Here are the accessible roles:
         *
         *  button:
         *
         *  Name "button text":
         */
        const button = getByRole("button", {name: /button texta/gi});

        expect(button).toBeTruthy();
    })
});