Cypress 트러블슈팅 가이드 실전

Cypress 테스트 작성 시 자주 발생하는 문제와 해결 방법을 다룹니다. 실무에서 바로 적용 가능한 트러블슈팅 기법을 학습합니다.

---

---

들어가며

이 글에서는 Cypress 트러블슈팅 가이드 실전에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. 비동기_요청_타임아웃_해결
2. Element_Detached_에러_해결
3. 로컬스토리지_상태_초기화
4. iframe_내부_요소_접근
5. CORS_에러_우회하기
6. 파일_업로드_테스트
7. 다중_탭_처리하기
8. 네트워크_지연_시뮬레이션
9. 조건부_테스트_처리
10. 스크롤_가능한_영역_테스트
11. 인증_토큰_주입하기
12. 테스트_재시도_설정

---

1. 비동기 요청 타임아웃 해결

개요

Cypress에서 API 호출이 느릴 때 타임아웃 에러가 발생합니다. timeout 옵션으로 대기 시간을 조정할 수 있습니다.

코드 예제

cy.request({
  url: '/api/slow-endpoint',
  timeout: 30000 // 30초로 연장
}).then((response) => {
  expect(response.status).to.eq(200);
});

설명

기본 타임아웃(5초) 대신 30초로 설정하여 느린 API 응답을 기다립니다. 네트워크가 느린 환경에서 유용합니다.

---

2. Element Detached 에러 해결

개요

DOM이 재렌더링될 때 요소가 분리되어 에러가 발생합니다. retry 기능으로 자동으로 재시도하게 할 수 있습니다.

코드 예제

cy.get('.dynamic-list')
  .find('.item')
  .should('have.length', 5)
  .first()
  .click();

설명

Cypress는 자동으로 요소를 재탐색하므로 should()로 상태를 확인한 후 작업하면 안전합니다.

---

3. 로컬스토리지 상태 초기화

개요

테스트 간 로컬스토리지 데이터가 남아있어 문제가 발생할 수 있습니다. beforeEach에서 초기화하여 깨끗한 상태를 유지합니다.

코드 예제

beforeEach(() => {
  cy.clearLocalStorage();
  cy.clearCookies();
  cy.visit('/');
});

설명

각 테스트 실행 전 로컬스토리지와 쿠키를 삭제하여 독립적인 테스트 환경을 보장합니다.

---

4. iframe 내부 요소 접근

개요

iframe 안의 요소는 일반적인 방법으로 접근할 수 없습니다. 커스텀 명령어를 만들어 해결합니다.

코드 예제

cy.iframe = () => {
  return cy.get('iframe')
    .its('0.contentDocument.body')
    .should('not.be.empty')
    .then(cy.wrap);
};

cy.iframe().find('.submit-btn').click();

설명

iframe의 contentDocument에 접근하여 내부 DOM을 Cypress 체이닝으로 조작할 수 있게 합니다.

---

5. CORS 에러 우회하기

개요

외부 API 호출 시 CORS 에러가 발생할 수 있습니다. cy.intercept()로 요청을 가로채서 모킹합니다.

코드 예제

cy.intercept('GET', '/api/external', {
  statusCode: 200,
  body: { data: 'mocked response' }
}).as('externalAPI');

cy.visit('/page');
cy.wait('@externalAPI');

설명

실제 외부 API 대신 가짜 응답을 반환하여 CORS 문제를 피하고 테스트 속도도 향상시킵니다.

---

6. 파일 업로드 테스트

개요

파일 입력 요소에 파일을 첨부하는 것은 까다롭습니다. cypress-file-upload 플러그인을 사용하거나 직접 구현합니다.

코드 예제

cy.get('input[type="file"]').selectFile({
  contents: 'cypress/fixtures/example.json',
  fileName: 'example.json',
  mimeType: 'application/json'
});

설명

selectFile() 명령어로 fixture 폴더의 파일을 업로드할 수 있습니다. Cypress 9.3.0 이상에서 기본 지원됩니다.

---

7. 다중 탭 처리하기

개요

Cypress는 기본적으로 다중 탭을 지원하지 않습니다. target 속성을 제거하여 같은 탭에서 처리합니다.

코드 예제

cy.get('a[target="_blank"]')
  .invoke('removeAttr', 'target')
  .click();

cy.url().should('include', '/new-page');

설명

새 탭으로 열리는 링크의 target 속성을 제거하면 현재 탭에서 페이지가 이동되어 테스트할 수 있습니다.

---

8. 네트워크 지연 시뮬레이션

개요

느린 네트워크 환경을 테스트하기 위해 인위적으로 지연을 추가할 수 있습니다.

코드 예제

cy.intercept('/api/data', (req) => {
  req.on('response', (res) => {
    res.setDelay(3000); // 3초 지연
  });
}).as('slowAPI');

설명

setDelay()로 응답 지연을 시뮬레이션하여 로딩 스피너나 타임아웃 처리를 테스트합니다.

---

9. 조건부 테스트 처리

개요

요소가 존재할 때만 특정 동작을 수행하고 싶을 때 조건부 로직을 사용합니다.

코드 예제

cy.get('body').then(($body) => {
  if ($body.find('.modal').length > 0) {
    cy.get('.modal .close-btn').click();
  }
});

설명

jQuery 스타일로 요소 존재 여부를 확인한 후 조건부로 동작을 실행합니다. 선택적 팝업 처리에 유용합니다.

---

10. 스크롤 가능한 영역 테스트

개요

무한 스크롤이나 특정 영역 스크롤이 필요한 경우 scrollIntoView()를 사용합니다.

코드 예제

cy.get('.scrollable-container')
  .scrollTo('bottom');

cy.get('.item-100')
  .scrollIntoView()
  .should('be.visible');

설명

컨테이너를 맨 아래로 스크롤하거나 특정 요소가 보일 때까지 스크롤할 수 있습니다.

---

11. 인증 토큰 주입하기

개요

로그인 과정을 매번 반복하지 않고 토큰을 직접 주입하여 테스트 속도를 높입니다.

코드 예제

cy.window().then((win) => {
  win.localStorage.setItem('authToken',
    'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
});
cy.visit('/dashboard');

설명

로컬스토리지에 미리 토큰을 저장한 후 페이지를 방문하면 로그인 상태로 시작할 수 있습니다.

---

12. 테스트 재시도 설정

개요

불안정한 테스트는 자동 재시도를 설정하여 false positive를 줄일 수 있습니다.

코드 예제

it('flaky test', { retries: 2 }, () => {
  cy.visit('/random-page');
  cy.get('.dynamic-element')
    .should('be.visible');
});

설명

실패 시 최대 2번까지 자동으로 재시도하여 일시적인 타이밍 이슈로 인한 실패를 방지합니다.

---

마치며

이번 글에서는 Cypress 트러블슈팅 가이드 실전에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#Cypress #E2E Testing #Debugging #Async Handling #Test Automation