> [!date] published: 2025-05-30
## 쿼리 메소드
[About Queries \| Testing Library](https://testing-library.com/docs/queries/about/)
`*AllBy*` 계열의 쿼리는 1개 이상의 Element를 찾는다.
### `getBy*` / `getAllBy*`
get => 해당하는 요소가 없으면 **에러를 던진다.**
`getBy*` 의 경우에는 **하나 이상의 요소가 매칭되면 에러**를 던진다.
### `queryBy*` / `queryAllBy*`
query => 해당하는 요소가 없으면 **null을 반환한다.**
**요소가 존재하지 않음을 확인**할 때 유용하다.
`queryBy*` 의 경우에는 **하나 이상의 요소가 매칭되면 에러**를 던진다.
### `findBy*` / `findAllBy*`
find => Promise를 반환한다. (비동기로 동작한다). 기본적으로 1000ms 타임아웃을 갖는다.
요소가 존재하지 않으면 reject된다.
`findBy*` 의 경우에는 **하나 이상의 요소가 매칭되면 reject**된다.
--
`findBy` 메소드는 `getBy*` 와 `waitFor`의 조합으로 대신할 수 있다.
## 우선순위
[Guiding Principles](https://testing-library.com/docs/guiding-principles/)에 따라서, 테스트는 사용자가 코드를 이용해서 상호작용하는 방식과 유사해야 한다.
이런 철학을 기반으로 해서 Testing Library에서는 쿼리 메소드를 사용하는 것에 대한 우선순위를 권장하고 있다. [Priority \| Testing Library](https://testing-library.com/docs/queries/about/#priority)
> [!note]
> 단지 "권장" 하는 것이기 때문에 라이브러리 상에서 우선순위를 적용하고 있지는 않다.
> 개발자가 테스트 코드를 짤 때 이 우선순위를 염두에 두기를 바라는 것
### 1. 접근성 기반
1. `getByRole`
```ts
// ✅ 버튼 찾기
screen.getByRole("button", { name: /submit/i });
// ✅ 입력 필드 찾기
screen.getByRole("textbox", { name: /username/i });
// ✅ 링크 찾기
screen.getByRole("link", { name: /learn more/i });
// ✅ 헤딩 찾기
screen.getByRole("heading", { level: 1 });
```
접근성 트리에서 보이는 모든 요소를 쿼리할 수 있다.
name 옵션을 이용해서 접근 가능한 이름으로 필터링할 수 있다.
2. `getByLabelText`
```ts
// ✅ 라벨과 연결된 입력 필드
screen.getByLabelText("Email Address");
// ✅ aria-label 지원
screen.getByLabelText("Search");
// ✅ aria-labelledby 지원
screen.getByLabelText("Choose your country");
```
form 필드에서 사용
실제로 사용자가 form을 사용할 때 label을 이용해서 element를 찾기 때문에 그 행동을 모방하는 이 방법을 가장 최우선으로 사용하는 것이 좋다.
3. `getByPlaceholderText`
label을 이용하는 것이 가장 좋지만, 없다면 placeholder를 사용하는 것이 그나마 낫다.
```ts
screen.getByPlaceholderText("Enter your email...");
```
4. `getByText`
form이 아닌 경우라면 텍스트 콘텐츠는 사용자가 요소를 찾는 주요 방법이다.
div나 span, paragraph 같은 비대화형 요소인 경우에 이 방법을 사용할 수 있다.
```ts
// ✅ 비대화형 요소 (div, span, p)
screen.getByText("Welcome to our app");
// ✅ 정규식 사용
screen.getByText(/hello world/i);
```
5. `getByDisplayValue`
form에서 현재 채워진 값을 기준으로 확인해야 하는 경우에 사용할 수 있다.
```ts
screen.getByDisplayValue("
[email protected]");
```
### 2. HTML5 and ARIA compliant selectors
1. `getByAltText`
대체 텍스트를 지원하는 요소인 경우
```ts
screen.getByAltText("Profile");
```
2. `getByTitle`
[title 속성](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title)을 이용하기
title 속성은 스크린 리더가 일관되게 읽지 않고, 시력이 있는 사용자가 title을 기본적으로 볼 수 없기 때문에 낮은 우선순위를 갖는다.
### 3. Test IDs - `getByTestId`
Test ID는 사용자가 실제로 보거나 들을 수 없기 때문에
role이나 text를 사용할 수 없고, 의미가 없는 경우에만 최후의 수단으로 사용한다.