설치 전 준비물

  • Node.js와 npm
  • Chrome 계열 브라우저
  • ChatGPT 앱의 Codex, Codex CLI, Claude Code와 Cursor 등 지원 에이전트
  • 브라우저로 확인할 수 있는 로컬 개발 서버

안전하게 사용하는 방법

  1. 운영 계정 대신 테스트 계정을 사용합니다.
  2. 결제와 삭제는 테스트 환경에서만 실행합니다.
  3. 실행 전 테스트 계획을 읽고 범위를 확인합니다.
  4. 실패 결과를 수정한 뒤 같은 테스트를 다시 실행합니다.
  5. 중요한 흐름은 Expect 결과에만 의존하지 말고 고정 자동화 테스트로 남깁니다.

Expect는 빠른 탐색 테스트에 강하지만 모든 결과가 항상 정확하다는 뜻은 아닙니다. 에이전트가 무엇을 눌렀고 어떤 상태를 근거로 통과시켰는지 재생 결과와 로그를 확인해야 합니다.

가장 간단한 설치

프로젝트 터미널에서 공식 초기화 명령을 실행합니다.

npx -y expect-cli@latest init

초기화 과정에서 에이전트 스킬 설치 여부를 묻는다면 사용할 도구에 맞춰 설치합니다. 스킬만 별도로 추가하려면 다음 명령을 사용할 수 있습니다.

npx -y skills add https://github.com/millionco/expect --skill expect -y

설치 후 에이전트를 새로 시작하고 /expect를 실행해 인식 여부를 확인합니다.

첫 테스트 실행하기

먼저 애플리케이션 개발 서버를 켭니다. 그다음 에이전트에 테스트 대상과 실패 조건을 구체적으로 말합니다.

/expect
회원가입 화면을 정상 입력으로 완료한 뒤,
빈 값 제출과 잘못된 이메일, 가입 버튼 연속 클릭도 확인해줘.
콘솔 오류와 실패한 네트워크 요청도 같이 점검해줘.

CLI로 직접 실행할 때는 주소와 테스트 지시를 함께 전달합니다.

expect-cli -u http://localhost:5173 -m "로그인 성공과 실패, 빈 값 제출을 테스트" -y

공식 README 기준 기본 테스트 대상은 현재 변경 사항(changes)입니다. 커밋하지 않은 수정만 좁혀 확인하려면 -t unstaged, 특정 브랜치 차이를 확인하려면 -t branch를 사용합니다. 여러 에이전트가 설치돼 자동 감지가 엇갈릴 때는 -a codex나 -a claude로 실행 주체를 지정할 수 있습니다.

expect-cli -t unstaged -a codex -u http://localhost:5173 \
  -m "수정한 가입 폼만 정상·빈 값·중복 제출 순서로 확인" -y

로그인과 쿠키를 안전하게 다루기

Expect는 로그인 상태를 재사용하기 위해 실제 브라우저 프로필의 쿠키를 읽을 수 있습니다. 이 기능은 편리하지만 개인 메일, 결제 수단과 관리자 권한이 연결된 기본 프로필을 그대로 쓰면 테스트 범위가 지나치게 넓어집니다.

  • 공개 화면은 먼저 --no-cookies로 실행합니다.
  • 로그인이 필요하면 서비스별 테스트 계정만 들어 있는 별도 Chrome 프로필을 만들고 --profile <이름>으로 지정합니다.
  • 결제, 탈퇴, 데이터 삭제 버튼은 스테이징 환경에서만 허용합니다.
  • 실행 전 계획을 직접 승인하려면 -y를 빼고 예상 클릭과 입력 범위를 읽습니다.
  • CDP 주소를 넘기는 --cdp는 해당 브라우저 세션 전체에 접근할 수 있으므로 공유 주소로 노출하지 않습니다.

공식 안내상 CI 모드는 --ci를 사용합니다. 이 모드는 헤드리스 실행, 쿠키 추출 생략, 계획 자동 승인과 30분 제한을 적용하므로 로그인 없는 공개 흐름이나 전용 테스트 자격 증명으로 구성한 시나리오에 더 적합합니다.

실행이 안 될 때 확인 순서

  1. 개발 서버 주소를 브라우저에서 직접 열어 보고 포트가 맞는지 확인합니다.
  2. expect-cli --version이 인식되지 않으면 npx -y expect-cli@latest --version으로 패키지 실행 자체를 확인합니다.
  3. 에이전트가 /expect를 찾지 못하면 초기화 명령을 다시 실행해 스킬 설치 대상을 확인한 뒤 에이전트를 완전히 새로 시작합니다.
  4. 여러 에이전트 중 잘못 감지됐다면 -a codex처럼 제공자를 지정합니다.
  5. 로그인 화면에서만 막히면 먼저 headed 모드와 테스트 프로필로 실행하고, 공개 화면은 --no-cookies로 분리해 원인을 좁힙니다.

초기화만 되돌리려면 먼저 npx -y skills list로 설치 위치와 이름을 확인한 뒤 npx -y skills remove expect를 실행합니다. expect-cli를 전역 설치한 경우에만 npm uninstall -g expect-cli를 추가로 실행합니다. 프로젝트 코드 변경은 별개이므로 삭제 전에 git diff로 Expect가 수정한 파일과 사용자가 작성한 파일을 구분해야 합니다.

현재 지원 범위에서 주의할 점

Expect 공식 FAQ는 모바일 테스트를 아직 제공 예정 기능으로 표시합니다. 따라서 “모바일도 확인”이라는 문장만으로 실제 모바일 뷰포트 검증이 됐다고 판단하면 안 됩니다. 반응형 레이아웃은 프로젝트의 기존 Playwright 테스트나 브라우저 개발자 도구에서 320px·768px 같은 목표 폭을 별도로 확인하고, Expect에는 데스크톱 사용자 흐름과 콘솔·네트워크 실패 탐색을 맡기는 식으로 역할을 나눕니다.

또한 Expect는 변경 코드를 바탕으로 탐색 계획을 생성하므로 같은 입력이 항상 같은 경로를 재현하는 고정 회귀 테스트와는 성격이 다릅니다. 가입, 결제, 권한 변경처럼 실패 비용이 큰 흐름은 Expect가 발견한 사례를 Playwright나 Cypress 테스트로 옮겨 CI에서 반복 재현할 수 있게 남깁니다.

Expect는 무엇인가

Expect는 AI 에이전트가 변경된 코드를 읽고 테스트 계획을 만든 뒤 실제 브라우저에서 기능을 확인하도록 돕는 도구입니다. 단순히 화면이 보이는지만 확인하지 않고 빈 값 제출, 잘못된 입력, 중복 클릭과 뒤로 가기처럼 사용자가 실수할 상황도 시도하도록 설계됐습니다.

설치 명령과 실제 브라우저 테스트 흐름을 보여주는 Expect 공식 사이트

어떤 문제를 찾는가

  • 버튼과 링크가 실제로 작동하는지
  • 입력 오류 메시지가 보이는지
  • 브라우저 콘솔 오류가 발생하는지
  • 변경된 화면에서 성능 문제가 커졌는지
  • 로그인 흐름과 뒤로 가기에서 상태가 깨지는지
  • 메타데이터나 연결이 빠진 페이지가 있는지