以下這段是 Playwright 安裝好後的範例：

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

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');

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

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

先從 @playwright/test 引入 test 和 expect，接著以 test 開頭定義一個測試案例，並給這個測試案例一個名稱：get started link，裡面就是整個測試步驟啦！

在這段範例裡面我們可以看到第一步是前往 https://playwright.dev 這個網址，接著點擊 Get started 這個 link，最後預期會看見 Installation 這個標題，是不是非常的簡潔、清晰、易懂呢？

操作步驟的撰寫格式為await page.locator.action()，因此要撰寫一個測試，首先需要來認識一下 Playwright 的元素定位 (locator) 方式，如果我們看到一段 html 是這樣：

page.getByRole( )

這個方法是透過 ARIA role 及 ARIA attribute 來定位，當我們想要定位「Dog」前方的 checkbox 元素時，可以寫 getByRole('checkbox', { name: 'Dog' })，如果要定位「GO！」這個按鈕，可以寫 getByRole('button', { name: 'GO！' })

💡Tips：
完整可以使用的 role 請參考 Playwright 文件

page.getByText( )

這個定位方式最簡單直接，畫面上看的見的文字都能定位，所以我們可以定位：

• getByText('Hello World') → 定位到 Hello World 這個標題
• getByText('account') → 定位到 account 這個 label
• getByText('First Cat') 定位到 First Cat 這個 div
• getByText('Cat') → 會同時選到 2 個 Cat 文字
• getByText('Dog') → 定位到 Dog 文字
• getByText('GO！') → 定位到 GO！ 文字

小小提醒！getByText() 定位的是「文字」，所以當我們寫getByText('Dog')的時候，定位的是 Dog 這個字而不是前方的 checkbox 唷！

💡Tips：
記得文字必須要一模一樣才能精準定位喔！如果文字中有空格，也必須放上去，建議使用複製貼上的方法確保完全一致，可以避免無法定位的問題。

page.getByLabel( )

如果 input 欄位有互相匹配的 label，這時我們除了直接定位 input 本身之外，也可以經由定位 label 直接選取互相匹配的 input，假設我們想要定位

<input type="text" id="ID">

這個欄位，它的外面有一個Label，那我們可以使用 getByLabel()這個方法，直接寫成getByLabel('account')就能定位到這個 input 了。

page.getByPlaceholder( )

如果 input 欄位有 placeholder 屬性，這時候我們就可以使用 getByPlaceholder() 來定位，像是

<input type="input" placeholder="name">

就可以使用getByPlaceholder('name')來定位這個 input，是不是非常方便呢？

page.getByTitle( )

上方的 html 內容，我們可以看到 「GO！」這個按鈕有 title 屬性

<button title="next">GO！</button>

這個時候，我們除了使用上面介紹的getByRole()以及getByText()之外，還能使用getByTitle()來定位，只需要用getByTitle('next')也能夠定位到 「GO！」這個按鈕。

page.getByAltText( )

當圖片有 alt 屬性時，我們就可以使用 getByAltText() 來定位，例如有兩張圖片：

<img alt='cat picture'>
<img alt='dog picture'>

想要定位第一張圖片可以使用getByAltText(cat picture)，定位第二張圖片可以使用getByAltText(dog picture)，在定位圖片時，這個方法非常的簡單方便。

page.getByTestId( )

最後，Playwright 也提供以 test id 來定位元素的方法，預設是data-testid，如果有自訂的 test id 則需要在 config 裡另外設置，例如開發團隊自訂 test id 屬性名稱為 data-catAndDog，元素 html 為

<span data-catAndDog="team">Our Team</span>

先到 playwright.config.ts 設置以下內容：

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-catAndDog'
  }
});

這樣就能透過 page.getByTestId('team') 來定位 「Our Team」 這個 span 囉！

最後，如果想要直接用 CSS 或是 XPath 來定位也是可以的喔！用 CSS 來定位的話，格式為 locator(css='') 以及 locator(xpath='')，也可以直接省略css 及 xpath 前綴，例如：

• page.locator('h1') → 定位到 Hello World 這個標題
• page.locator('#id') → 定位到 這個 input
• page.locator('input[type="checkbox"]') → 定位到 Dog 前面的 checkbox
• page.locator(//button) → 用 XPath 定位到 button

到這裡，我們認識了 Playwright 提供多樣且完整的元素定位 API，讓玩家們在撰寫腳本時，可以迅速找到目標，各位可以依據需求選擇適合的 API 使用。接下來，我們要繼續認識 Playwright 提供的動作(action)，與元素定位(locator)組合起來，就能實際操作網頁啦！