ByRole[Testing Library]

SnowCat·2023년 3월 3일

Testing Library

목록 보기

2/11

getByRole(
  container?: HTMLElement,
  role: string,
  options?: {
    hidden?: boolean = false,
    name?: TextMatch,
    description?: TextMatch,
    selected?: boolean,
    checked?: boolean,
    pressed?: boolean,
    suggest?: boolean,
    current?: boolean | string,
    expanded?: boolean,
    queryFallbacks?: boolean,
    level?: number,
  }): HTMLElement

HTML에 있는 role 속성을 활용해 쿼리를 작성할 수 있음
role은 따로 명시하지 않아도 태그마다 암묵적으로 가지고 있는 속성이 있음 (ex: Button => button)
같은 페이지에 동일한 역할을 하는 엘리먼트가 여러개 있으면 옵션을 사용해 특정 요소만을 가져올 수 있음

Options

hidden

쿼리에 언급이 없으면 테스트 중에 aria-hidden 속성의 값을 가져오지 않음
아래 예제에서 open dialog 엘리먼트를 가져오고 싶으면 hidden: true 속성을 부여해야 함

const Element = (
  <body>
    <main aria-hidden="true">
      <button>Open dialog</button>
    </main>
    <div role="dialog">
      <button>Close dialog</button>
    </div>
  </body>
);

test ("hidden test", () => {
  render(<Element />)
  const noHiddenElement = screen.getByRole("button");
  const hiddenElement = screen.getByRole("button", {hidden: true});
}

selected

엘리먼트의 selected 상태를 구분하기 위해 가져오기 위해 selected 옵션 사용

const Element = (
  <body>
    <div role="tablist">
      <button role="tab" aria-selected="true">Native</button>
      <button role="tab" aria-selected="false">React</button>
      <button role="tab" aria-selected="false">Cypress</button>
    </div>
  </body>
)

test ("select test", () => {
  render(<Element />)
  const noSelectedElement = screen.getByRole("button");
  const selectedElement = screen.getByRole("button", {hidden: true});
}

checked

체크박스와 같은 엘리먼트에서 체크 여부를 확인하기 위해 사용

const Element = (
  <body>
    <section>
      <button role="checkbox" aria-checked="true">Sugar</button>
      <button role="checkbox" aria-checked="false">Gummy bears</button>
      <button role="checkbox" aria-checked="false">Whipped cream</button>
    </section>
  </body>
)

test ("check test", () => {
  render(<Element />)
  const noCheckedElement = screen.getByRole("button");
  const checkedElement = screen.getByRole("button", {checked: true});
}

current

aria-current: 현재 보고있는 요소를 강조하는 속성
aria-current값의 기본값은 false임에 유의

const Element = (
  <body>
    <nav>
      <a href="current/page" aria-current="true">👍</a>
      <a href="another/page">👎</a>
    </nav>
  </body>
)

test ("current test", () => {
  render(<Element />)
  const uncurrentElement = screen.getByRole("button");
  const currentElement = screen.getByRole("button", {current: true});
}

pressed

엘리먼트가 눌러져있는 상태인지 테스트

const Element = (
  <body>
    <section>
      <button aria-pressed="true">👍</button>
      <button aria-pressed="false">👎</button>
    </section>
  </body>
)

test ("pressed test", () => {
  render(<Element />)
  const noPressedElement = screen.getByRole("button");
  const pressedElement = screen.getByRole("button", {: true});
}

suggest

쿼리 제안을 보여줄 수 있는 옵션으로, 기본값은 false
더 나은 쿼리방법이 있을경우 테스트를 실패로 만들고 더 나은 쿼리 방법에 대한 제안을 보여줌

expanded

확장가능한 요소를 가져올 수 있는 옵션

const Element = (
  <body>
    <nav>
      <ul>
        <li>
          <a aria-expanded="false" aria-haspopup="true" href="..."
            >Expandable Menu Item</a
          >
          <ul>
            <li><a href="#">Submenu Item 1</a></li>
            <li><a href="#">Submenu Item 1</a></li>
          </ul>
        </li>
        <li><a href="#">Regular Menu Item</a></li>
      </ul>
    </nav>
  </body>
  
  
)

test ("expand test", () => {
  render(<Element />)
  const unExpandedElement = screen.getByRole("link", {expanded: false});
}

queryFallbacks

엘리먼트에 role이 여러개 있는 경우 쿼리는 기본값인 상태에서 맨 처음 role만을 판단함
여러개의 role을 모두 검사하고 싶으면 queryFallbacks 옵션을 true로 설정해야 함

level

heading role을 가지고 있을 때 구체적인 aria-level을 통해 heading의 수준을 표기할 수 있음
level 속성을 가지는 엘리먼트는 getByRole('heading', { level: number })을 통해 가져올 수 있음
level 옵션은 role이 heading일 때만 사용 가능하며, 다른 role에 사용시 에러가 발생함
heading과 aria-level이 명시된 엘리먼트뿐만 아니라 h1-h6태그도 가져옴에 주의

const Element = (
  <body>
    <section>
      <h1>Heading Level One</h1>
      <h2>First Heading Level Two</h2>
      <h3>Heading Level Three</h3>
      <div role="heading" aria-level="2">Second Heading Level Two</div>
    </section>
  </body>
)

test ("level test", () => {
  render(<Element />)
  const h1Element = screen.getByRole("heading", {level: 1});
  const h2AndDivElemnt = screen.getByRole("heading", {level: 2});
}

description

이름은 없지만 접근성을 위한 설명만 존재하는 경우 description옵션을 통해 엘리먼트를 가져올 수 있음

const Element = (
  <body>
    <ul>
      <li role="alertdialog" aria-describedby="notification-id-1">
        <div><button>Close</button></div>
        <div id="notification-id-1">You have unread emails</div>
      </li>
      <li role="alertdialog" aria-describedby="notification-id-2">
        <div><button>Close</button></div>
        <div id="notification-id-2">Your session is about to expire</div>
      </li>
    </ul>
  </body>
)

test ("description test", () => {
  render(<Element />)
  const expireElement = screen.getByRole('alertdialog', {description: 'Your session is about to expire'})
}