#การใช้งาน Playwright CLI ในการสร้าง Script กรณีทดสอบ

Playwright CLI เป็น command-line interface สำหรับ browser automation ที่ออกแบบมาให้เหมาะกับ Coding Agent เช่น Claude Code, GitHub Copilot, Cursor หรือ agent อื่นที่สามารถเรียกคำสั่ง shell ได้ โดยแนวคิดสำคัญคือให้ Agent สำรวจหน้าเว็บผ่าน browser, อ่าน snapshot ของหน้า, อ้างอิง element ด้วย ref และนำ Playwright code ที่ CLI สร้างออกมาไปประกอบเป็น test script

จุดเด่นคือ Agent ไม่จำเป็นต้องรับ tool schema ขนาดใหญ่เข้า context ตลอดเวลาเหมือนแนวทาง MCP แต่สามารถเรียกคำสั่งสั้น ๆ เช่น open, fill, click, snapshot และ generate-locator แล้วนำผลลัพธ์ที่ได้ไปสร้างกรณีทดสอบต่อได้

บทความนี้อ้างอิง Playwright Agent CLI Documentation ณ วันที่ 22 กันยายน 2026

#1. Playwright CLI คืออะไร

Playwright CLI ในเอกสาร Agent CLI ใช้คำสั่งหลักชื่อ

playwright-cli

ตัวอย่างเช่น

playwright-cli open https://demo.playwright.dev/todomvc --headed

จากนั้นสามารถสั่ง browser ได้โดยตรง

playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

หลังคำสั่งแต่ละครั้ง CLI จะส่งข้อมูลสถานะของหน้าออกมา เช่น

  • URL ปัจจุบัน
  • Page Title
  • Accessibility Snapshot
  • Element refs เช่น e1, e5, e21
  • Playwright code ที่ใช้ทำ action นั้น

องค์ประกอบเหล่านี้ทำให้ Coding Agent สามารถเข้าใจหน้าเว็บและสร้าง test script ได้อย่างเป็นขั้นตอน

#2. Playwright CLI ต่างจาก Playwright Test CLI อย่างไร

ควรแยกสองคำสั่งนี้ให้ออกจากกัน

#Playwright Agent CLI

playwright-cli ...

หรือ

npx playwright cli ...

ใช้สำหรับ

  • ควบคุม browser แบบทีละ action
  • ให้ Coding Agent สำรวจ application
  • อ่าน accessibility snapshot
  • สร้าง locator
  • สร้าง raw Playwright code
  • บันทึก interaction
  • ช่วยสร้างและซ่อม test

#Playwright Test CLI

npx playwright test

ใช้สำหรับ

  • รัน test suite
  • เลือก test file
  • debug test
  • เปิด UI Mode
  • เลือก browser/project
  • สร้าง report

ดังนั้น workflow ที่เหมาะสมคือ

Coding Agent
     |
     v
Playwright CLI
     |
     | Explore / Generate
     v
*.spec.ts
     |
     v
Playwright Test
     |
     v
Test Result / Trace / Report

#3. Requirements

เอกสาร Playwright ระบุว่า Playwright CLI ต้องการ

  • Node.js 20 ขึ้นไป
  • Coding Agent เช่น Claude Code, GitHub Copilot หรือระบบลักษณะเดียวกัน

ตรวจสอบ Node.js

node --version

ตัวอย่างผลลัพธ์

v22.x.x

#4. ติดตั้ง Playwright CLI

#วิธีที่ 1: Global Installation

npm install -g @playwright/cli@latest

ตรวจสอบคำสั่ง

playwright-cli --help

ตรวจสอบ version

playwright-cli --version

#วิธีที่ 2: ใช้ Playwright ที่อยู่ใน Project

หาก project มี Playwright อยู่แล้ว สามารถตรวจสอบได้ด้วย

npx --no-install playwright --version

จากนั้นเรียก Agent CLI ได้ด้วย

npx playwright cli --help

กล่าวคือ

playwright-cli open https://example.com

และ

npx playwright cli open https://example.com

สามารถใช้ในลักษณะเดียวกันได้

#5. Initialize Workspace

เริ่มต้น workspace ด้วย

playwright-cli install

คำสั่งนี้จะเตรียม directory สำหรับ CLI และ browser ที่ต้องใช้งาน

โครงสร้างโดยประมาณ

project/
├── .playwright/
├── tests/
├── package.json
└── playwright.config.ts

#6. ติดตั้ง Skills สำหรับ Coding Agent

หากต้องการให้ Coding Agent เข้าใจ workflow ของ Playwright CLI ได้ดีขึ้น สามารถติดตั้ง Skills

#Claude Code

playwright-cli install --skills

หรือ

playwright-cli install --skills=claude

โครงสร้างที่ได้โดยประมาณ

.claude/
└── skills/
    └── playwright-cli/

#Agent ที่รองรับ .agents

playwright-cli install --skills=agents

จะได้

.agents/
└── skills/
    └── playwright-cli/

#ติดตั้งแบบ Global

playwright-cli install --skills -g

Skills ช่วยให้ agent เข้าใจเรื่องสำคัญ เช่น

  • Browser interaction
  • Snapshot และ refs
  • Test generation
  • Debugging
  • Request mocking
  • Storage state
  • Tracing
  • Video recording

#7. แนวคิด Snapshot และ Element Ref

หัวใจของ Playwright CLI คือ Accessibility Snapshot

เมื่อเปิดหน้าเว็บ

playwright-cli open https://example.com/login --headed

CLI จะสร้าง snapshot ของหน้า และ element ต่าง ๆ อาจถูกกำหนด ref เช่น

textbox "Email" [ref=e1]
textbox "Password" [ref=e2]
button "Sign In" [ref=e3]

เราสามารถสั่ง

playwright-cli fill e1 "student@example.com"

จากนั้น

playwright-cli fill e2 "password123"

และ

playwright-cli click e3

ข้อดีคือ Agent ไม่จำเป็นต้องเดา CSS selector ตั้งแต่แรก

#8. สร้างกรณีทดสอบ Login ด้วย Playwright CLI

สมมติ application มีหน้า

http://localhost:3000/login

และต้องการทดสอบ

ผู้ใช้กรอก email/password ถูกต้อง แล้วสามารถเข้าสู่หน้า dashboard ได้

#Test Case

Field Value
Test Case ID TC-LOGIN-001
Scenario Login สำเร็จ
Preconditions ผู้ใช้มี account
Email student@example.com
Password password123
Expected Result Redirect ไป /dashboard

#9. เปิด Browser

playwright-cli open http://localhost:3000/login --headed

Agent จะได้รับ snapshot ของหน้า

ตัวอย่างแนวคิด

textbox "Email" [ref=e1]
textbox "Password" [ref=e2]
button "Login" [ref=e3]

#10. กรอก Email

playwright-cli fill e1 "student@example.com"

Playwright CLI สามารถแสดง code ที่ใช้จริงออกมา เช่น

await page.getByRole('textbox', { name: 'Email' })
  .fill('student@example.com');

นี่คือจุดสำคัญ เพราะ code ดังกล่าวสามารถนำไปใช้ใน test script ได้ทันที

#11. กรอก Password

playwright-cli fill e2 "password123"

ตัวอย่าง code ที่ได้

await page.getByRole('textbox', { name: 'Password' })
  .fill('password123');

#12. Click Login

playwright-cli click e3

ตัวอย่าง code

await page.getByRole('button', { name: 'Login' }).click();

#13. ตรวจสอบสถานะหลัง Login

สร้าง snapshot ใหม่

playwright-cli snapshot

จากนั้น Agent สามารถตรวจสอบ

  • URL
  • Heading
  • User menu
  • Dashboard content

เช่นพบ

heading "Dashboard" [ref=e10]

สามารถนำไปสร้าง assertion

await expect(
  page.getByRole('heading', { name: 'Dashboard' })
).toBeVisible();

#14. Test Script ที่ได้

นำ code ที่ Playwright CLI สร้างให้มาประกอบเป็น test

สร้างไฟล์

tests/login.spec.ts

import { test, expect } from '@playwright/test';

test('TC-LOGIN-001 user can login successfully', async ({ page }) => {

  await page.goto('http://localhost:3000/login');

  await page
    .getByRole('textbox', { name: 'Email' })
    .fill('student@example.com');

  await page
    .getByRole('textbox', { name: 'Password' })
    .fill('password123');

  await page
    .getByRole('button', { name: 'Login' })
    .click();

  await expect(page).toHaveURL(/dashboard/);

  await expect(
    page.getByRole('heading', { name: 'Dashboard' })
  ).toBeVisible();

});

#15. รัน Test Script

npx playwright test tests/login.spec.ts

เปิด browser ระหว่างทดสอบ

npx playwright test tests/login.spec.ts --headed

Debug

npx playwright test tests/login.spec.ts --debug

UI Mode

npx playwright test --ui

#16. สร้าง Locator ด้วย generate-locator

หาก snapshot มี element

button "Add to cart" [ref=e5]

สามารถใช้

playwright-cli generate-locator e5

ผลลัพธ์อาจเป็น

getByRole('button', { name: 'Add to cart' })

จากนั้นนำไปใช้เป็น

await page
  .getByRole('button', { name: 'Add to cart' })
  .click();

#17. ตรวจสอบ Attribute ของ Element

หากต้องการอ่าน attribute ที่ snapshot ไม่แสดง เช่น

  • id
  • class
  • data-testid

สามารถใช้ eval

playwright-cli eval "el => el.id" e5

หรือ

playwright-cli eval \
"el => el.getAttribute('data-testid')" e5

ตัวอย่างผลลัพธ์

login-button

จากนั้นสามารถสร้าง locator

page.getByTestId('login-button')

#18. Recording Interaction

ในบางกรณี flow อธิบายยาก เช่น

  • Drag & Drop
  • Canvas
  • Complex UI interaction
  • Multi-step form

สามารถเปิด browser

playwright-cli open https://example.com --headed

เริ่ม recording

playwright-cli recording-start

จากนั้นทำ interaction ผ่าน browser

หยุด recording

playwright-cli recording-stop

CLI จะส่ง Playwright code ของ interaction ที่บันทึกไว้กลับมา

แนวทางนี้เหมาะสำหรับนำ flow ที่ผู้ใช้ทำจริงมาแปลงเป็น automation script

#19. Workflow สำหรับสร้าง Test ด้วย Coding Agent

เอกสาร Playwright แนะนำแนวคิดหลัก 3 ขั้น

Plan
  |
  v
Generate
  |
  v
Heal

#Step 1: Plan

ให้ Agent สำรวจ application ก่อน

Prompt ตัวอย่าง

Use Playwright CLI to explore http://localhost:3000.

Create test scenarios for the login feature.

Cover:
1. valid login
2. invalid password
3. empty email
4. empty password
5. invalid email format

Do not create the final test files yet.
First produce a test plan.

Agent สามารถใช้

playwright-cli open ...
playwright-cli snapshot
playwright-cli click ...
playwright-cli fill ...

เพื่อทำความเข้าใจ application

#Step 2: Generate

เมื่อได้ test plan แล้ว จึงให้ Agent สร้าง automation

Prompt

Use the Playwright CLI to execute each scenario in the login test plan.

Collect the generated Playwright code and create:

tests/login.spec.ts

Use @playwright/test and add meaningful assertions.
Prefer getByRole, getByLabel and getByTestId locators.

Agent จะสำรวจหน้าและนำ code ที่ CLI สร้างไปสร้าง test file

#Step 3: Run

npx playwright test

#Step 4: Heal

หาก test fail เพราะ UI เปลี่ยน เช่น

page.locator('#login-btn')

ไม่พบ element แล้ว

ให้ Agent เปิด test ที่ล้มเหลวใน debug mode แล้วสำรวจ DOM/snapshot ใหม่ เพื่อสร้าง locator ที่เหมาะสมกว่า

ตัวอย่างแนวคิด

Old locator

#login-btn

        |
        v

Playwright CLI explores current UI

        |
        v

New locator

getByRole('button', { name: 'Login' })

นี่คือแนวคิด Plan → Generate → Heal

#20. ตัวอย่าง Prompt สำหรับ Coding Agent

#Prompt สร้าง Login Tests

Use Playwright CLI to inspect:

http://localhost:3000/login

Create Playwright Test scripts for these scenarios:

1. successful login
2. invalid password
3. empty email
4. empty password
5. invalid email format

Requirements:

- Use @playwright/test
- Put tests in tests/login.spec.ts
- Prefer role/label/test-id locators
- Add assertions for every scenario
- Do not use hard waits
- Take screenshot when a test fails
- Run the tests after generating them
- Repair failing locators when possible

#21. ตัวอย่าง Shopping Cart Test

สมมติระบบ

https://example.com/products

เปิดระบบ

playwright-cli open https://example.com/products --headed

snapshot อาจได้

heading "Products" [ref=e1]
button "Add to cart" [ref=e8]
link "Cart" [ref=e15]

เพิ่มสินค้า

playwright-cli click e8

เปิด Cart

playwright-cli click e15

snapshot

playwright-cli snapshot

จากนั้น Agent สามารถสร้าง test

import { test, expect } from '@playwright/test';

test('user can add product to cart', async ({ page }) => {

  await page.goto('https://example.com/products');

  await page
    .getByRole('button', { name: 'Add to cart' })
    .first()
    .click();

  await page
    .getByRole('link', { name: 'Cart' })
    .click();

  await expect(
    page.getByRole('heading', { name: 'Shopping Cart' })
  ).toBeVisible();

});

#22. ตัวอย่าง Negative Test

ตัวอย่าง login ด้วย password ผิด

test('TC-LOGIN-002 invalid password', async ({ page }) => {

  await page.goto('/login');

  await page
    .getByLabel('Email')
    .fill('student@example.com');

  await page
    .getByLabel('Password')
    .fill('wrong-password');

  await page
    .getByRole('button', { name: 'Login' })
    .click();

  await expect(
    page.getByText('Invalid email or password')
  ).toBeVisible();

});

Coding Agent สามารถใช้ Playwright CLI เพื่อสำรวจข้อความ error จริงก่อนสร้าง assertion

#23. ใช้ Session แยกงานทดสอบ

Playwright CLI รองรับ named sessions

ตัวอย่าง

playwright-cli -s=admin open http://localhost:3000

อีก session

playwright-cli -s=user open http://localhost:3000

เหมาะกับ

  • Admin/User
  • Buyer/Seller
  • Teacher/Student
  • Multi-user workflow

ตัวอย่างแนวคิด

Session: admin
     |
     +---- Approve order

Session: user
     |
     +---- Create order

#24. Authentication State

ระบบที่ต้อง login ซ้ำ ๆ สามารถใช้ storage state ช่วยลดเวลา

หลัง login แล้ว

playwright-cli state-save auth.json

ครั้งถัดไป

playwright-cli state-load auth.json

แนวคิดเดียวกับ Playwright storage state คือ reuse authentication state ระหว่างการทดสอบ

ไม่ควร commit credential หรือ authentication state ที่มีข้อมูลสำคัญลง public repository

#25. Screenshot

ถ่าย screenshot

playwright-cli screenshot

เหมาะสำหรับ

  • เก็บหลักฐาน test
  • ตรวจสอบ UI
  • ให้ Agent วิเคราะห์ state
  • ใช้ประกอบ bug report

#26. Tracing

Tracing ช่วยเก็บข้อมูลการทำงานของ browser

playwright-cli tracing-start

ทำ test flow

playwright-cli click e5
playwright-cli fill e7 "example"

แล้วหยุด

playwright-cli tracing-stop

เหมาะกับการ debug test ที่ทำงานไม่ตรงกับที่คาด

#27. Network Inspection

Playwright CLI รองรับการตรวจสอบ network request

ตัวอย่าง

playwright-cli requests

สามารถนำไปใช้ตรวจสอบ

  • REST API
  • GraphQL
  • Request headers
  • Response body
  • Error response
  • API ที่ frontend เรียกหลัง click

ทำให้ Agent ไม่ได้ทดสอบเพียง UI แต่สามารถช่วยวิเคราะห์ integration ระหว่าง frontend และ backend ได้ด้วย

#28. ตัวอย่าง Workflow สำหรับสร้าง Test Script ทั้งระบบ

Requirements
     |
     v
Coding Agent
     |
     v
Playwright CLI
     |
     +---- Open Application
     |
     +---- Inspect Snapshot
     |
     +---- Discover Elements
     |
     +---- Execute Test Flow
     |
     +---- Generate Locators
     |
     +---- Collect Playwright Code
     |
     v
Playwright Test Files
     |
     v
npx playwright test
     |
     +---- Pass
     |
     +---- Fail
            |
            v
        Debug / Heal
            |
            v
       Updated Test

#29. Recommended Project Structure

playwright-project/
│
├── tests/
│   ├── auth/
│   │   ├── login.spec.ts
│   │   └── logout.spec.ts
│   │
│   ├── products/
│   │   └── product.spec.ts
│   │
│   └── cart/
│       └── cart.spec.ts
│
├── pages/
│   ├── LoginPage.ts
│   └── ProductPage.ts
│
├── test-data/
│   └── users.json
│
├── .playwright/
├── playwright.config.ts
├── package.json
└── README.md

สำหรับ project ใหญ่ ควรให้ Agent แยก generated test ออกจาก page objects และ test data อย่างชัดเจน

#30. Best Practices

#30.1 ให้ Agent สำรวจก่อน Generate

ไม่ควรให้ Agent เดา selector จาก source code อย่างเดียว

ควรใช้

Explore → Snapshot → Locate → Execute → Generate

#30.2 ใช้ User-Facing Locator

แนะนำ

page.getByRole(...)
page.getByLabel(...)
page.getByPlaceholder(...)
page.getByText(...)
page.getByTestId(...)

หลีกเลี่ยง locator ที่ผูกกับ implementation มากเกินไป เช่น

page.locator('div:nth-child(5) > button')

#30.3 Generated Code ต้องมี Assertion

เพียง interaction อย่างเดียว

await page.getByRole('button', { name: 'Login' }).click();

ยังไม่ใช่ test ที่สมบูรณ์

ต้องมี expected result เช่น

await expect(page).toHaveURL(/dashboard/);

#30.4 หลีกเลี่ยง Hard Wait

ไม่แนะนำ

await page.waitForTimeout(5000);

ควรใช้ Playwright auto-waiting และ web-first assertions

await expect(
  page.getByRole('heading', { name: 'Dashboard' })
).toBeVisible();

#30.5 ให้ Agent Run Test หลัง Generate

workflow ที่ดีคือ

Generate
   |
   v
Run
   |
   +---- Pass
   |
   +---- Fail
          |
          v
        Heal

ไม่ควรถือว่า generated script ถูกต้องจนกว่าจะรันจริง

#31. Playwright CLI vs Codegen

Playwright มี code generator แบบดั้งเดิม

npx playwright codegen https://example.com

เหมาะกับ

คนเปิด browser → ทำ interaction → Playwright record code

Playwright Agent CLI เหมาะกับ

Coding Agent → สำรวจ browser → อ่าน snapshot → ทำ action → สร้าง code → สร้าง test → run → debug

ดังนั้นสองเครื่องมือไม่ได้แทนกันทั้งหมด แต่เหมาะกับ workflow คนละแบบ

Feature Playwright Codegen Playwright Agent CLI
ผู้ควบคุมหลัก Developer Coding Agent
Recording ดีมาก รองรับ
Snapshot/refs ไม่ใช่ workflow หลัก เป็น core concept
Agent workflow จำกัด ออกแบบมาโดยตรง
Generate locator มี มี
Plan → Generate → Heal ไม่ใช่ workflow หลัก รองรับโดย Skills
Automation ผ่าน shell บางส่วน เหมาะมาก

#32. Playwright CLI vs Playwright MCP

Playwright documentation แยก use case โดยประมาณดังนี้

#Playwright CLI

เหมาะกับ

  • Coding Agent
  • Agent ที่ทำงานกับ repository ขนาดใหญ่
  • ต้องการใช้ context อย่างประหยัด
  • workflow ผ่าน shell commands

#Playwright MCP

เหมาะกับ

  • Agentic loop ที่ใช้ MCP tool calls
  • Interactive browser exploration
  • Application ที่ agent ใช้ MCP ecosystem อยู่แล้ว

Conceptual architecture

Playwright CLI

Agent
  |
 Shell Command
  |
  v
playwright-cli
  |
  v
Browser

เทียบกับ

Playwright MCP

Agent
  |
 MCP Tool Call
  |
  v
Playwright MCP Server
  |
  v
Browser

#33. Prompt Template สำหรับ Project จริง

สามารถนำ prompt ต่อไปนี้ไปใช้กับ Coding Agent ได้

You are a software test automation engineer.

Use Playwright CLI to explore the application:

http://localhost:3000

Goal:
Generate maintainable Playwright Test scripts.

Workflow:

1. Explore the application using Playwright CLI.
2. Inspect accessibility snapshots.
3. Identify stable locators.
4. Create a test plan.
5. Execute each scenario through Playwright CLI.
6. Collect the generated Playwright code.
7. Convert the generated actions into @playwright/test specs.
8. Add meaningful assertions.
9. Run all generated tests.
10. Investigate and repair failed tests.

Locator priority:

1. getByRole
2. getByLabel
3. getByTestId
4. getByText
5. CSS locator only when necessary

Rules:

- Do not use hard waits.
- Do not assert implementation details.
- Keep each test independent.
- Use descriptive test names.
- Add screenshots/traces for failures.

#34. ตัวอย่าง Prompt ภาษาไทย

ใช้ Playwright CLI สำรวจระบบที่

http://localhost:3000

จากนั้นสร้างกรณีทดสอบ Playwright Test สำหรับระบบ Login

ให้ครอบคลุม

1. Login สำเร็จ
2. Password ไม่ถูกต้อง
3. Email ว่าง
4. Password ว่าง
5. Email format ไม่ถูกต้อง

ขั้นตอนที่ต้องทำ

1. เปิดระบบด้วย Playwright CLI
2. อ่าน accessibility snapshot
3. หา locator ที่เสถียร
4. ทดลองทำแต่ละ scenario จริง
5. นำ Playwright code ที่ CLI สร้างออกมาสร้าง test
6. เพิ่ม assertion
7. บันทึกเป็น tests/login.spec.ts
8. รัน test
9. หาก test fail ให้สำรวจหน้าใหม่และแก้ locator
10. สรุปผลการทดสอบ

ให้ใช้ locator ตามลำดับความสำคัญ

getByRole
getByLabel
getByTestId
getByText

หลีกเลี่ยง hard-coded CSS selector และ waitForTimeout

#35. สรุป

Playwright CLI ทำให้ workflow การสร้าง automated test ด้วย AI Coding Agent มีลักษณะเป็นระบบมากขึ้น เพราะ Agent สามารถเข้าไปสำรวจ application จริงผ่าน browser, อ่าน accessibility snapshot, ใช้ refs เพื่อ interact กับ element และนำ code ที่ได้จากแต่ละ action ไปสร้าง Playwright Test

แนวทางที่แนะนำคือ

Requirement
    ↓
Test Plan
    ↓
Explore with Playwright CLI
    ↓
Snapshot + Refs
    ↓
Execute Scenario
    ↓
Generated Playwright Code
    ↓
Add Assertions
    ↓
Create *.spec.ts
    ↓
npx playwright test
    ↓
Debug / Heal

ดังนั้น Playwright CLI ไม่ได้เป็นเพียงเครื่องมือสั่ง browser จาก terminal แต่สามารถทำหน้าที่เป็น browser automation interface สำหรับ Coding Agent และเป็นส่วนสำคัญของ workflow แบบ Plan → Generate → Heal สำหรับการสร้างและดูแล automated test scripts

#References