본문으로 건너뛰기
effidevFlutter · Cloudflare 엣지 · 클라우드 비용 최적화

Playwright CLI 사용법, 깔기 전 확인할 것

Playwright CLI 사용법 설치는 두 줄이지만 폴더 밖에도 파일이 깔린다

핵심 요약

설치는 두 줄인데 폴더 밖에도 파일이 깔린다. 마이크로소프트 공식 Playwright CLI 0.1.24를 직접 설치해 확인한 것과 권한·세션 주의, 에이전트에게 맡기는 순서를 정리했다.

코딩 에이전트가 “로그인 화면 고쳤어요”라고 말했는데, 그 화면을 브라우저에서 한 번이라도 눌러 봤는지는 알 수 없다. 코드가 맞아 보이는 것과 눌렀을 때 실제로 되는 것은 다르다. 에이전트에게 브라우저를 직접 열어 눌러 보게 하는 도구가 Playwright CLI다.

이 글은 Claude Code나 Codex, GitHub Copilot 같은 코딩 에이전트를 쓰지만 “만든 화면을 직접 눌러 보는 일”까지는 맡겨 본 적 없는 사람을 위해 썼다. 결론부터 적는다. 마이크로소프트가 낸 공식 도구이고, 설치는 명령 두 줄이다. 다만 두 번째 줄은 작업 폴더에 스킬 파일을 만드는 데서 끝나지 않는다. 빈 폴더에서 직접 돌려 보니 윈도우에서는 폴더 밖 사용자 캐시에도 파일을 내려받았다. 그리고 그 스킬 파일에는 에이전트가 따로 묻지 않고 실행할 수 있는 명령 목록이 들어 있다. 깔기 전에 이 두 가지는 알고 있는 편이 좋다.

먼저 말 몇 개를 풀어 둔다. 코딩 에이전트는 코드를 쓰고 터미널 명령까지 실행하는 AI다. CLI는 글자 명령으로 쓰는 프로그램이다. 스킬은 에이전트가 읽는 사용 설명서 파일(SKILL.md)이다. 에이전트는 이 파일을 읽고 도구 쓰는 법을 익힌다. 토큰은 AI가 읽고 쓰는 글자 조각이고, 많이 쓸수록 한도와 비용이 줄어든다. 헤드리스는 화면 없이 브라우저를 돌리는 방식이다.

한눈에 보기: 2026년 11월 12일 확인

항목 내용
만든 곳 마이크로소프트. npm 패키지 이름은 @playwright/cli, 저자 표기는 Microsoft Corporation
라이선스 Apache-2.0
최신 버전 0.1.24 (11월 10일 릴리스)
GitHub 별 15,132개, 포크 915개, 열린 이슈·풀 리퀘스트 합쳐 2개 (오후 확인)
요구 사양 Node.js 20 이상 (README 기준, 아래 “버전 표기가 어긋난 곳” 참고)
설치 명령 두 줄
기본 동작 헤드리스, 브라우저 프로필은 메모리에만 둔다
형제 도구 Playwright MCP: 별 39,530개, 최신 v0.0.85 (11월 9일)

릴리스 간격은 들쭉날쭉하다. 저장소 릴리스 목록에서 최근 네 번이 9월 18일(v0.1.21), 9월 28일(v0.1.22), 10월 31일(v0.1.23), 11월 10일(v0.1.24)이다. 버전이 0.1.x라는 점은 명령이 바뀔 수 있다는 신호로 읽는 게 안전하다.

에이전트는 이 도구로 무엇을 하나: 열고, 입력하고, 눌러 보고, 화면을 찍는다

README가 보여 주는 데모는 에이전트에게 이렇게 말하는 것이다.

Use playwright skills to test https://demo.playwright.dev/todomvc/.
Take screenshots for all successful and failing scenarios.

그러면 에이전트가 터미널에서 playwright-cli 명령을 하나씩 실행한다. README는 사람이 같은 일을 손으로 해 보는 순서도 적어 두었다.

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli check e21
playwright-cli screenshot

여기서 e21 이 무엇인지 짚고 가야 한다. 명령을 실행할 때마다 도구는 현재 페이지의 주소·제목과 함께 스냅샷 파일(페이지를 글로 옮긴 목록) 경로를 알려 준다. 공식 문서는 이 파일에 요소 번호(ref)가 붙은 접근성 트리가 들어 있다고 설명한다. 접근성 트리는 화면 낭독기가 읽는 구조, 즉 “버튼, 입력칸, 체크박스” 같은 목록이다. 에이전트는 이 목록에서 e21 같은 번호를 보고 “이걸 체크해”라고 말한다. 화면 좌표를 눈으로 맞추는 게 아니라 번호로 가리키는 방식이다. CSS 선택자나 Playwright의 역할 기반 선택(getByRole('button', { name: 'Submit' }))으로 가리킬 수도 있다고 README에 적혀 있다.

공식 문서의 특징 목록에는 하나가 더 있다. 브라우저를 계속 떠 있는 프로세스로 두기 때문에 명령마다 브라우저를 새로 켜는 시간이 들지 않는다는 설명(daemon architecture)이다. 우리가 시간을 재 본 것은 아니다.

설치 두 줄을 직접 따라 해 봤다

README의 설치는 아래 두 줄이다.

npm install -g @playwright/cli@latest
playwright-cli install --skills

이 글을 쓰면서 윈도우 11(Node.js 24.22.1, npm 11.19.1)에서 아래처럼 확인했다. 전역 설치(-g) 대신 새 빈 폴더에 로컬로 깔았다. 실험이 끝나면 폴더만 지우면 되기 때문이다. 원문 그대로 실행한 것이 아니라는 점은 밝혀 둔다.

단계 확인한 것
npm install @playwright/cli@0.1.24 패키지 3개, 약 2초. node_modules는 19MB. 공개된 패키지 정보의 scripts 항목은 test 하나뿐이고, 설치 때 자동으로 도는 스크립트는 없다
playwright-cli --version 0.1.24
playwright-cli --help 첫 줄이 run playwright mcp commands from terminal. 명령이 100개쯤 나열된다. 스킬 파일(SKILL.md)의 위치도 알려 준다
playwright-cli install --skills (빈 작업 폴더에서) 작업 폴더에 .claude/skills/playwright-cli/ 가 생겼다. SKILL.md 1개와 references/ 문서 10개다. .playwright 폴더도 생겼다
같은 명령, 폴더 밖 %LOCALAPPDATA%\ms-playwright 에 FFmpeg(내려받기 1.6MiB)와 Winldd(0.1MiB)를 받았다. 디스크에는 합쳐 약 4MB가 남았다

마지막 줄이 이 글의 제목이 된 이유다. 두 번째 설치 명령(install)은 도움말에서 “initialize workspace”(작업 공간 초기화)라고 소개되는데, 실제로는 작업 폴더 밖 사용자 폴더에도 쓴다. 영상 녹화에 쓰는 FFmpeg와 윈도우용 보조 도구로 보이지만 용도를 문서에서 확인한 것은 아니다. 브라우저 본체(크로미움 등)는 이 명령이 받지 않았다. 도움말에 install-browser 라는 별도 명령이 있다. 출력을 앞 20줄까지만 봤기 때문에 내려받는 파일이 이것뿐인지는 장담하지 못한다. 확인이 끝난 뒤 이 캐시 폴더는 내가 만든 것이어서 지웠다.

install --skills 의 옵션도 도움말에서 확인했다. --skills 의 값은 claude(기본값)와 agents 중 하나이고, --global(-g)을 주면 작업 폴더 대신 홈 디렉터리에 스킬을 설치한다. agents 쪽 설치 위치는 확인하지 않았다. 설치된 SKILL.md 는 GitHub 저장소 main 브랜치의 같은 파일과 글자 단위로 같았다.

README에는 스킬 없이 쓰는 방법도 있다. 에이전트에게 “playwright-cli를 쓰고, playwright-cli --help 로 명령을 확인해”라고만 말하면 에이전트가 도움말을 읽고 스스로 익힌다는 것이다. 스킬 파일을 깔고 싶지 않을 때의 길이다.

스킬 파일이 에이전트에게 미리 허락하는 것

설치된 SKILL.md 맨 위에는 이런 머리말이 있다.

---
name: playwright-cli
description: Automate browser interactions, test web pages and work with Playwright tests.
allowed-tools: Bash(playwright-cli:*) Bash(npx playwright:*) Bash(npx --no-install playwright:*)
---

allowed-tools 는 이 스킬이 켜져 있는 동안 에이전트가 사용자에게 묻지 않고 실행할 수 있도록 미리 허락해 두는 명령 목록이다(Claude Code 스킬 형식의 항목이고, 에이전트 제품마다 처리 방식은 다를 수 있으니 쓰는 제품의 문서로 확인해야 한다). 위 줄은 playwright-cli 로 시작하는 셸 명령 전부와 npx playwright 로 시작하는 명령 전부를 뜻한다.

이게 왜 중요한가. playwright-cli 명령 중에는 run-code 가 있다. 참조 문서에 따르면 이 명령은 “임의의 Playwright 코드”를 실행한다. 코드는 함수 하나여야 하고, 격리된 환경에서 돈다. require, process, Node 모듈은 쓸 수 없고 fetch와 타이머는 쓸 수 있다고 적혀 있다. 그 격리가 실제로 어디까지 막는지는 이 글이 확인하지 못했다. 그래도 “명령 하나만 허락했다”고 생각하고 깔면 허락 범위를 잘못 아는 것이다. SKILL.md 본문에도 “패키지 설치와 사용자 정의 npm 스크립트는 별도 승인이 필요할 수 있다”는 문장이 있다.

스킬 파일이 에이전트에게 읽히는 설명서이자 권한 목록이라는 점은 이 블로그가 앞서 다룬 SKILL.md 표준 이야기와 이어진다. 스킬은 편하지만 설치하는 순간 내 에이전트의 행동 범위가 넓어진다. 확장을 깔았다가 사고가 난 사례는 클로드 코드 확장 백도어 글에, 설치기가 훅을 대신 승인하는 코드는 Postman 자동 설치 글에 정리했다. Playwright CLI는 마이크로소프트 공식이고 Apache-2.0 라이선스이며 설치 스크립트가 없다는 점에서 그 사례들과 성격이 다르다. 그래도 권한 목록을 읽고 깔자는 결론은 같다.

깔기 전에 알아 둘 일곱 가지

README, 참조 문서, 패키지 소스에서 읽은 내용을 위험의 순서로 모았다. “글에 적힌 것”과 “우리 의견”을 구분했다.

무엇 글에 적힌 것 그래서
로그인 상태가 파일로 남는다 state-save 는 쿠키와 localStorage를 JSON 파일로 저장한다. 문서 예시에 세션 쿠키 이름·값이 들어 있다 그 파일은 비밀번호만큼 민감하다. 저장소에 올리지 않는다 (우리 의견)
프로필이 디스크에 남는다 기본은 메모리 프로필이고, --persistent 나 --profile=<경로> 를 주면 디스크에 남는다 실제 서비스 계정 로그인은 테스트 계정으로만 (우리 의견)
웹 페이지가 에이전트에게 말을 건다 WebMCP(페이지가 에이전트용 도구를 등록하는 실험 기능) 절에 “이름·설명·결과는 페이지에서 온 것이라 신뢰할 수 없는 입력이며 지시가 아니다”라고 적혀 있다 에이전트가 읽는 페이지에 숨은 지시문이 있을 수 있다는 일반적 위험이다. 모르는 사이트에는 쓰지 않는다 (우리 의견)
출처 허용·차단 설정은 방벽이 아니다 환경 변수 설명에 허용·차단 출처 목록은 “보안 경계가 아니고 리디렉션에 영향을 주지 않는다”고 적혀 있다 이 설정만 믿고 외부 접속을 막았다고 보지 않는다
파일 접근 기본은 작업 폴더 안으로 제한되고 file:// 주소로의 이동도 막힌다. PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS 를 켜면 풀린다 이 스위치는 켜지 않는다 (우리 의견)
업데이트 확인 소스(playwright-cli.js)를 읽으면 open, attach, list, install, install-browser 를 실행할 때 하루에 한 번까지 npm view 로 새 버전을 묻는다. 환경 변수 NO_UPDATE_NOTIFIER 나 CI 가 있으면 건너뛴다 외부 접속을 막은 환경에서는 이 환경 변수를 둔다 (우리 의견)
알파 빌드에 묶여 있다 저장소 package.json 의 의존성이 playwright 와 playwright-core 의 1.66.0-alpha-… 빌드로 고정돼 있다. 설치해 보니 패키지 3개가 이 구성이었다 안정판 위에 얹은 도구가 아니다. 쓰는 동안 버전을 고정해 두는 편이 낫다 (우리 의견)

버전 표기가 어긋난 곳

작은 일이지만 하나 있다. 저장소 main 브랜치의 README는 “Node.js 20 이상”이라고 적는다. 11월 11일 올라온 변경(#538)이 예전의 “Node.js 18” 표기를 고친 것이다. 그런데 npm에 올라가 있는 0.1.24의 engines 항목은 아직 node >=18 이다. 설치해 보니 같이 깔리는 playwright 와 playwright-core 의 engines 는 node >=20 이었다. 도구 본체가 걸러 주는 기준이 문서와 실제 의존성보다 느슨하다는 뜻이니, Node 18을 쓰고 있다면 20 이상으로 올리고 시작하는 게 안전하다. 다음 릴리스에서 맞춰질 것으로 보이지만 확인한 것은 아니다.

CLI냐 MCP냐: 마이크로소프트가 말하는 차이와 우리가 확인하지 못한 것

Playwright에는 같은 일을 하는 길이 하나 더 있다. MCP(에이전트가 외부 도구를 부르는 규격. 자세한 내용은 MCP 2026-07-28 스펙 글에 있다)로 연결하는 Playwright MCP다. 공식 문서와 README가 둘의 차이를 이렇게 설명한다.

구분 Playwright CLI Playwright MCP
어울리는 곳 큰 코드베이스를 다루는 코딩 에이전트 탐색형 자동화, 스스로 고치는 테스트, 오래 도는 자율 작업
동작 방식 에이전트가 셸 명령을 실행한다 모델이 구조화된 인자로 도구를 부른다
토큰 비용 낮다 (명령 출력이 짧고 스킬을 필요할 때 읽는다) 높다 (도구 설명서와 스냅샷이 맥락에 들어간다)
기본 모드 헤드리스 헤드(화면 있음)
설정 npm install -g @playwright/cli MCP 클라이언트의 JSON 설정

README는 CLI가 토큰을 아끼는 이유를 “큰 도구 설명서와 장황한 접근성 트리를 모델의 맥락에 올리지 않기 때문”이라고 쓴다. 반대로 MCP는 브라우저 상태를 계속 쥐고 있어야 하는 작업에서는 토큰 비용보다 그 장점이 크다고 인정한다.

여기서 선을 그어 둔다. “CLI가 토큰을 덜 쓴다”는 마이크로소프트의 설명이지 우리가 잰 값이 아니다. 공식 문서에도 몇 퍼센트라는 숫자는 없다. 같은 작업을 CLI와 MCP로 시켜 토큰 수를 비교한 결과를 이 글은 갖고 있지 않다. 비교해 보고 싶다면 같은 프롬프트로 두 방식을 각각 돌리고, 에이전트 제품이 보여 주는 사용량 표시를 읽는 것이 가장 단순하다.

스킬 참조 문서에 든 열 가지 일

설치된 스킬에는 references/ 폴더가 있고 README가 이를 “특정 작업 안내서”로 소개한다. 문서 10개를 초심자 말로 풀면 이렇다.

안내서 무슨 일
Playwright 테스트 실행·디버깅 이미 있는 테스트 묶음을 돌리고, 멈춘 지점에 붙어서 살펴본다
요청 가로채기(mocking) 서버 응답을 가짜로 바꿔서 오류 화면 같은 걸 일부러 만들어 본다
Playwright 코드 실행 위 run-code. 위치 정보 허용 같은 설정을 코드로 건다
브라우저 세션 관리 이름 붙인 브라우저를 여러 개 따로 둔다
저장 상태(쿠키·localStorage) 로그인 상태를 저장하고 다시 불러온다
테스트 생성(plan → generate → heal) 화면을 둘러보고 계획을 세우고 테스트 코드를 만들고 깨진 테스트를 고친다
트레이싱 실행 기록을 남겨 나중에 되짚는다
영상 녹화 브라우저 사용 장면을 영상으로 남긴다. 장(chapter) 표시도 넣을 수 있다
PR에 스크린샷·영상 첨부 gh 2.99 이상의 --attach 로 화면 증거를 풀 리퀘스트에 올린다
요소 속성 읽기 스냅샷에 안 보이는 id·class 같은 속성을 읽는다

테스트 생성 문서가 설명하는 원리가 흥미롭다. playwright-cli 로 한 동작은 하나하나 그에 해당하는 Playwright 코드(TypeScript)로 출력된다. 예를 들어 fill e1 "user@example.com" 을 실행하면 await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com'); 가 함께 나온다. 이 코드를 모으면 그대로 테스트 파일이 된다는 설명이다. 에이전트에게 “이 화면을 눌러 보고, 눌러 본 순서를 테스트로 남겨 줘”라고 시킬 수 있다는 뜻이다. 다만 이 흐름을 이번에 실행해 보지는 않았다.

PR 첨부 문서는 한도를 적어 두었다. 이미지는 10MB까지, 영상은 무료 요금제에서 10MB·유료에서 100MB까지이고, 영상에는 대체 텍스트를 붙일 수 없다. 첨부하려면 저장소에 쓰기 권한이 있어야 하고, GitHub.com과 GitHub Enterprise Cloud에서만 된다.

세션과 프로필: 로그인 상태가 어디에 남는지

브라우저를 어떻게 여느냐에 따라 로그인 상태가 남는 곳이 달라진다. README의 내용을 표로 모았다.

방식 명령 로그인 상태
기본 playwright-cli open <주소> 메모리에만 있다. 같은 세션의 명령들 사이에서는 유지되고 브라우저를 닫으면 사라진다
영구 프로필 open --persistent 디스크에 저장돼 브라우저를 다시 켜도 남는다
프로필 폴더 지정 open --profile=<경로> 그 폴더에 남는다
이름 붙인 세션 -s=이름 또는 --session 이름 프로젝트마다 다른 브라우저를 쓴다. 환경 변수 PLAYWRIGHT_CLI_SESSION=이름 으로 에이전트 실행 때 한꺼번에 줄 수도 있다
저장 파일 state-save, state-load 쿠키와 localStorage가 JSON 파일로 남는다 (위 표 첫 줄 참고)

세션 관리도 README에 있다. 화면 없는 세션은 한 시간 동안 명령이 없으면 스스로 종료된다. open --idle-timeout=<밀리초> 로 바꾸고 0 이면 끄는 것이다. 화면이 있는(--headed) 브라우저는 계속 열려 있다. 정리 명령은 list(세션 목록), close-all(전부 닫기), kill-all(남은 브라우저 프로세스 강제 종료)이다. 에이전트가 백그라운드에서 브라우저를 돌릴 때는 playwright-cli show 로 전체 세션을 한눈에 보는 대시보드를 열 수 있고, 거기서 직접 끼어들어 조작할 수도 있다고 README가 설명한다.

처음 20분: 내 프로젝트에서 시험하는 순서

바로 쓰려면 이 순서를 권한다. 이 가운데 1~3번은 이 글에서 직접 해 본 단계이고, 4번부터는 문서에 있는 순서를 정리한 것이다.

  1. 쓰던 프로젝트가 아니라 빈 폴더나 복제본에서 시작한다. 시험 대상은 내 컴퓨터에서 돌리는 개발 서버 주소나 연습용 페이지(README가 쓰는 demo.playwright.dev/todomvc)로 한다.
  2. 전역 설치(-g) 대신 그 폴더에 로컬로 설치한다. 업데이트 안내문에도 로컬 설치용 명령(npm install --save-dev @playwright/cli@latest)이 있다. 안 맞으면 폴더째 지우면 된다.
  3. playwright-cli install --skills 를 실행하고, 생긴 .claude/skills/playwright-cli/SKILL.md 를 열어서 allowed-tools 줄을 읽는다. 이 줄이 내 에이전트에게 주는 허락이다. 폴더 밖 캐시(ms-playwright)가 생겼는지도 본다.
  4. 브라우저 설치는 문서에서 별도 명령(install-browser)으로 보이지만, 처음 open 했을 때 어떻게 안내되는지는 이 글이 확인하지 못했다. 안내 문구를 읽고 따른다.
  5. 에이전트에게 README의 데모 문장을 그대로 준다. “이 주소를 playwright skills로 테스트하고, 성공과 실패 장면마다 스크린샷을 찍어 줘.”
  6. 끝나면 결과 파일을 본다. 스냅샷은 .playwright-cli/ 폴더에 날짜가 붙은 .yml 파일로 쌓인다고 README 예시가 보여 준다.
  7. 마무리한다. playwright-cli list 로 남은 세션을 보고 close-all 을 실행한다. state-save 로 만든 JSON 이 있으면 지운다.

초심자가 가장 많이 막히는 곳은 에이전트가 번호를 잘못 가리키는 경우일 것이다. 그럴 때는 playwright-cli snapshot 으로 최신 목록을 다시 받으라고 시키면 된다. 번호(e21)는 페이지가 바뀌면 달라질 수 있기 때문이다. 큰 페이지에서는 find "Add to cart" 처럼 글자로 찾는 명령이 있다. 전체 스냅샷을 다 읽는 대신 일치하는 부분과 앞뒤 3줄만 돌려준다고 README가 설명한다.

윈도우를 쓴다면 SKILL.md 의 작은 경고도 알아 두자. 주소에 & 가 여러 개 들어가면 cmd.exe 와 PowerShell이 & 를 명령 구분자로 읽어서 주소가 잘린다. cmd.exe 에서는 ^& 로, PowerShell에서는 --% 를 앞에 붙여 쓰라고 적혀 있다.

이럴 때는 다른 길이 낫다

  • 에이전트 없이 사람이 테스트를 짜는 경우에는 이 도구가 필요 없다. Playwright 자체의 테스트 실행기를 쓰면 된다. README도 CLI를 “코딩 에이전트를 쓰는 경우”에 맞춘 도구라고 소개한다.
  • 브라우저 상태를 오래 쥐고 이어 가야 하는 탐색형 작업은 README가 MCP 쪽을 권하는 영역이다.
  • 실제 서비스 계정, 결제, 회사 내부 시스템에 에이전트를 붙이는 용도로는 이 글만 읽고 결정하지 않는 게 좋다. 이 글은 도구의 구조와 문서를 읽은 것이지 그런 환경에서 안전성을 시험한 글이 아니다.

이 글이 확인하지 못한 것

  • 브라우저를 실제로 띄워 TodoMVC 데모를 돌려 보지 않았다. 설치·도움말·스킬 파일 생성까지만 직접 확인했다.
  • 토큰 절약은 측정하지 않았다. 공식 설명을 옮겼을 뿐이다.
  • 에이전트(Claude Code 등)에 스킬을 물려 실제로 시켜 보지 않았다. allowed-tools 가 각 제품에서 정확히 어떻게 처리되는지도 확인하지 않았다.
  • run-code 의 격리 범위, 출처 허용·차단의 실제 동작은 시험하지 않았다. 문서에 적힌 대로 옮겼다.
  • 윈도우 11 한 대에서만 확인했다. 맥·리눅스에서 install 이 폴더 밖에 무엇을 쓰는지는 모른다.
  • install 이 폴더 밖에 쓰는 파일이 FFmpeg와 Winldd뿐인지는 출력을 일부만 봐서 단정하지 않는다.
  • 별 수·릴리스·버전은 11월 12일 오후 기준이다. 이후 달라질 수 있다.

이 글의 근거 페이지

모두 11월 12일에 열어서 응답과 내용을 확인했다.