Laravel Dusk

• 介紹
• 安裝
  • 管理 ChromeDriver 安裝
  • 使用其他瀏覽器
• 開始使用
  • 產生測試
  • 每次測試後重置資料庫
  • 執行測試
  • 環境處理
• 瀏覽器基礎
  • 建立瀏覽器
  • 導覽
  • 調整瀏覽器視窗大小
  • 瀏覽器巨集
  • 身份驗證
  • Cookies
  • 執行 JavaScript
  • 擷取螢幕截圖
  • 將主控台輸出儲存到磁碟
  • 將頁面原始碼儲存到磁碟
• 與元素互動
  • Dusk 選擇器
  • 文字、值與屬性
  • 與表單互動
  • 附加檔案
  • 按下按鈕
  • 點擊連結
  • 使用鍵盤
  • 使用滑鼠
  • JavaScript 對話框
  • 與內嵌框架互動
  • 範圍化選擇器
  • 等待元素
  • 將元素捲動到檢視區
• 可用的斷言
• 頁面
  • 產生頁面
  • 配置頁面
  • 導覽至頁面
  • 縮寫選擇器
  • 頁面方法
• 元件
  • 產生元件
  • 使用元件
• 持續整合
  • Heroku CI
  • Travis CI
  • GitHub Actions
  • Chipper CI

介紹

Laravel Dusk 提供了一個表達力強、易於使用的瀏覽器自動化與測試 API。預設情況下，Dusk 不要求您在您的本機電腦上安裝 JDK 或 Selenium。取而代之的是，Dusk 使用了一個獨立的 ChromeDriver 安裝。但是，您可以自由使用任何其他與 Selenium 相容的驅動程式。

安裝

要開始使用，您應該安裝 Google Chrome 並將 laravel/dusk Composer 依賴套件新增到您的專案中：

composer require laravel/dusk --dev

⚠️ 警告

如果您手動註冊 Dusk 的服務提供者，您絕不應該在正式環境中註冊它，因為這樣做可能導致任意使用者能夠對您的應用程式進行身份驗證。

安裝 Dusk 套件後，執行 dusk:install Artisan 指令。dusk:install 指令將會建立 tests/Browser 目錄、一個範例 Dusk 測試，並為您的作業系統安裝 Chrome Driver 二進位檔：

php artisan dusk:install

接下來，設定您的應用程式 .env 檔案中的 APP_URL 環境變數。這個值應該與您用於在瀏覽器中存取應用程式的 URL 相符。

📌 備註

如果您正在使用 Laravel Sail 來管理您的本機開發環境，請也參閱 Sail 說明文件關於 設定和執行 Dusk 測試 的部分。

管理 ChromeDriver 安裝

如果您想安裝不同版本的 ChromeDriver，而非 Laravel Dusk 透過 dusk:install 指令所安裝的，您可以使用 dusk:chrome-driver 指令：

# Install the latest version of ChromeDriver for your OS...
php artisan dusk:chrome-driver

# Install a given version of ChromeDriver for your OS...
php artisan dusk:chrome-driver 86

# Install a given version of ChromeDriver for all supported OSs...
php artisan dusk:chrome-driver --all

# Install the version of ChromeDriver that matches the detected version of Chrome / Chromium for your OS...
php artisan dusk:chrome-driver --detect

⚠️ 警告

Dusk 需要 chromedriver 二進位檔是可執行的。如果您在執行 Dusk 時遇到問題，您應該使用以下指令確保二進位檔是可執行的：chmod -R 0755 vendor/laravel/dusk/bin/。

使用其他瀏覽器

預設情況下，Dusk 使用 Google Chrome 以及獨立的 ChromeDriver 安裝來執行您的瀏覽器測試。但是，您可以啟動您自己的 Selenium 伺服器，並針對您希望的任何瀏覽器執行測試。

要開始使用，請開啟您的 tests/DuskTestCase.php 檔案，該檔案是您應用程式的基礎 Dusk 測試案例。在這個檔案中，您可以移除對 startChromeDriver 方法的呼叫。這將會阻止 Dusk 自動啟動 ChromeDriver：

/**
 * Prepare for Dusk test execution.
 *
 * @beforeClass
 */
public static function prepare(): void
{
    // static::startChromeDriver();
}

接下來，您可以修改 driver 方法以連接到您選擇的 URL 與連接埠。此外，您可以修改應傳遞給 WebDriver 的「desired capabilities (期望功能)」設定：

use Facebook\WebDriver\Remote\RemoteWebDriver;

/**
 * Create the RemoteWebDriver instance.
 */
protected function driver(): RemoteWebDriver
{
    return RemoteWebDriver::create(
        'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
    );
}

開始使用

產生測試

要產生 Dusk 測試，請使用 dusk:make Artisan 命令。產生的測試將會放置在 tests/Browser 目錄中：

php artisan dusk:make LoginTest

每次測試後重置資料庫

您所編寫的大部分測試都會與從應用程式資料庫中檢索資料的頁面互動；然而，您的 Dusk 測試絕不應使用 RefreshDatabase trait。RefreshDatabase trait 利用了資料庫事務，這些事務將不適用或無法跨 HTTP 請求使用。相反地，您有兩種選擇：DatabaseMigrations trait 和 DatabaseTruncation trait。

使用資料庫遷移

DatabaseMigrations trait 將會在每次測試前執行您的資料庫遷移。然而，在每次測試前刪除並重新建立資料庫資料表通常比截斷資料表慢：

Pest

<?php

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;

uses(DatabaseMigrations::class);

//

PHPUnit

<?php

namespace Tests\Browser;

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    //
}

⚠️ 警告

執行 Dusk 測試時，不能使用 SQLite 記憶體中資料庫。由於瀏覽器在自己的行程中執行，因此它將無法存取其他行程的記憶體中資料庫。

使用資料庫截斷

DatabaseTruncation trait 將會在第一次測試時遷移您的資料庫，以確保您的資料庫資料表已正確建立。然而，在後續測試中，資料庫的資料表將會被簡單地截斷——這比重新執行所有資料庫遷移提供了速度提升：

Pest

<?php

use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;

uses(DatabaseTruncation::class);

//

PHPUnit

<?php

namespace Tests\Browser;

use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;

class ExampleTest extends DuskTestCase
{
    use DatabaseTruncation;

    //
}

預設情況下，此 trait 將會截斷除了 migrations 資料表之外的所有資料表。如果您想自訂應被截斷的資料表，您可以在測試類別上定義一個 $tablesToTruncate 屬性：

📌 備註

如果您正在使用 Pest，您應該在基礎 DuskTestCase 類別或您的測試檔案所繼承的任何類別上定義屬性或方法。

/**
 * Indicates which tables should be truncated.
 *
 * @var array
 */
protected $tablesToTruncate = ['users'];

或者，您可以在測試類別上定義一個 $exceptTables 屬性，以指定應從截斷中排除的資料表：

/**
 * Indicates which tables should be excluded from truncation.
 *
 * @var array
 */
protected $exceptTables = ['users'];

要指定應截斷其資料表的資料庫連線，您可以在測試類別上定義一個 $connectionsToTruncate 屬性：

/**
 * Indicates which connections should have their tables truncated.
 *
 * @var array
 */
protected $connectionsToTruncate = ['mysql'];

如果您想在執行資料庫截斷之前或之後執行程式碼，您可以在測試類別上定義 beforeTruncatingDatabase 或 afterTruncatingDatabase 方法：

/**
 * Perform any work that should take place before the database has started truncating.
 */
protected function beforeTruncatingDatabase(): void
{
    //
}

/**
 * Perform any work that should take place after the database has finished truncating.
 */
protected function afterTruncatingDatabase(): void
{
    //
}

執行測試

要執行您的瀏覽器測試，請執行 dusk Artisan 命令：

php artisan dusk

如果您上次執行 dusk 命令時有測試失敗，您可以透過使用 dusk:fails 命令首先重新執行失敗的測試來節省時間：

php artisan dusk:fails

dusk 命令接受 Pest / PHPUnit 測試執行器通常接受的任何引數，例如允許您僅執行特定 群組 的測試：

php artisan dusk --group=foo

📌 備註

如果您正在使用 Laravel Sail 管理您的本地開發環境，請查閱 Sail 文件中關於 配置與執行 Dusk 測試 的說明。

手動啟動 ChromeDriver

預設情況下，Dusk 將會自動嘗試啟動 ChromeDriver。如果這對您的特定系統不起作用，您可以在執行 dusk 命令之前手動啟動 ChromeDriver。如果您選擇手動啟動 ChromeDriver，您應該將您的 tests/DuskTestCase.php 檔案中的以下行註解掉：

/**
 * Prepare for Dusk test execution.
 *
 * @beforeClass
 */
public static function prepare(): void
{
    // static::startChromeDriver();
}

此外，如果您在 9515 以外的埠上啟動 ChromeDriver，您應該修改同一類別中的 driver 方法以反映正確的埠：

use Facebook\WebDriver\Remote\RemoteWebDriver;

/**
 * Create the RemoteWebDriver instance.
 */
protected function driver(): RemoteWebDriver
{
    return RemoteWebDriver::create(
        'http://localhost:9515', DesiredCapabilities::chrome()
    );
}

環境處理

為了強制 Dusk 在執行測試時使用其自己的環境檔案，請在您的專案根目錄中建立一個 .env.dusk.{environment} 檔案。例如，如果您將從 local 環境啟動 dusk 命令，您應該建立一個 .env.dusk.local 檔案。

執行測試時，Dusk 將會備份您的 .env 檔案並將您的 Dusk 環境重新命名為 .env。測試完成後，您的 .env 檔案將會被還原。

瀏覽器基礎

建立瀏覽器

首先，讓我們編寫一個測試來驗證我們能否登入應用程式。產生測試後，我們可以修改它以導覽至登入頁面，輸入一些憑證，然後點擊「Login」按鈕。要建立瀏覽器實例，您可以在 Dusk 測試中呼叫 browse 方法：

Pest

<?php

use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;

uses(DatabaseMigrations::class);

test('basic example', function () {
    $user = User::factory()->create([
        'email' => '[email protected]',
    ]);

    $this->browse(function (Browser $browser) use ($user) {
        $browser->visit('/login')
            ->type('email', $user->email)
            ->type('password', 'password')
            ->press('Login')
            ->assertPathIs('/home');
    });
});

PHPUnit

<?php

namespace Tests\Browser;

use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    /**
     * A basic browser test example.
     */
    public function test_basic_example(): void
    {
        $user = User::factory()->create([
            'email' => '[email protected]',
        ]);

        $this->browse(function (Browser $browser) use ($user) {
            $browser->visit('/login')
                ->type('email', $user->email)
                ->type('password', 'password')
                ->press('Login')
                ->assertPathIs('/home');
        });
    }
}

如您在上面的範例中看到的，browse 方法接受一個閉包。Dusk 會自動將瀏覽器實例傳遞給此閉包，這是用於與應用程式互動並進行斷言的主要物件。

建立多個瀏覽器

有時，您可能需要多個瀏覽器才能正確執行測試。例如，可能需要多個瀏覽器來測試與 WebSocket 互動的聊天畫面。要建立多個瀏覽器，只需向 browse 方法的閉包簽章中添加更多瀏覽器引數即可：

$this->browse(function (Browser $first, Browser $second) {
    $first->loginAs(User::find(1))
        ->visit('/home')
        ->waitForText('Message');

    $second->loginAs(User::find(2))
        ->visit('/home')
        ->waitForText('Message')
        ->type('message', 'Hey Taylor')
        ->press('Send');

    $first->waitForText('Hey Taylor')
        ->assertSee('Jeffrey Way');
});

導覽

visit 方法可用於導覽至應用程式內的給定 URI：

$browser->visit('/login');

您可以使用 visitRoute 方法導覽至具名路由：

$browser->visitRoute($routeName, $parameters);

您可以使用 back 和 forward 方法導覽「回上頁」和「下一頁」：

$browser->back();

$browser->forward();

您可以使用 refresh 方法重新整理頁面：

$browser->refresh();

調整瀏覽器視窗大小

您可以使用 resize 方法調整瀏覽器視窗的大小：

$browser->resize(1920, 1080);

maximize 方法可用於將瀏覽器視窗最大化：

$browser->maximize();

fitContent 方法將調整瀏覽器視窗大小以符合其內容：

$browser->fitContent();

當測試失敗時，Dusk 會在擷取螢幕截圖之前自動調整瀏覽器大小以符合內容。您可以透過在測試中呼叫 disableFitOnFailure 方法來禁用此功能：

$browser->disableFitOnFailure();

您可以使用 move 方法將瀏覽器視窗移動到螢幕上的不同位置：

$browser->move($x = 100, $y = 100);

瀏覽器巨集

如果您想定義一個可以在各種測試中重複使用的自訂瀏覽器方法，您可以使用 Browser 類別上的 macro 方法。通常，您應該從服務提供者的 boot 方法呼叫此方法：

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Browser;

class DuskServiceProvider extends ServiceProvider
{
    /**
     * Register Dusk's browser macros.
     */
    public function boot(): void
    {
        Browser::macro('scrollToElement', function (string $element = null) {
            $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");

            return $this;
        });
    }
}

macro 函數接受一個名稱作為其第一個引數，一個閉包作為其第二個引數。在 Browser 實例上呼叫該巨集方法時，巨集的閉包將被執行：

$this->browse(function (Browser $browser) use ($user) {
    $browser->visit('/pay')
        ->scrollToElement('#credit-card-details')
        ->assertSee('Enter Credit Card Details');
});

身份驗證

通常，您會測試需要身份驗證的頁面。您可以使用 Dusk 的 loginAs 方法，以避免在每個測試中都與應用程式的登入畫面互動。loginAs 方法接受與您的可驗證模型 (authenticatable model) 相關聯的主鍵或可驗證模型實例：

use App\Models\User;
use Laravel\Dusk\Browser;

$this->browse(function (Browser $browser) {
    $browser->loginAs(User::find(1))
        ->visit('/home');
});

[!WARNING] 使用 loginAs 方法後，使用者會話將在檔案中的所有測試中保留。

Cookies

您可以使用 cookie 方法來取得或設定加密的 cookie 值。預設情況下，由 Laravel 建立的所有 cookie 都已加密：

$browser->cookie('name');

$browser->cookie('name', 'Taylor');

您可以使用 plainCookie 方法來取得或設定未加密的 cookie 值：

$browser->plainCookie('name');

$browser->plainCookie('name', 'Taylor');

您可以使用 deleteCookie 方法刪除給定的 cookie：

$browser->deleteCookie('name');

執行 JavaScript

您可以使用 script 方法在瀏覽器中執行任意 JavaScript 語句：

$browser->script('document.documentElement.scrollTop = 0');

$browser->script([
    'document.body.scrollTop = 0',
    'document.documentElement.scrollTop = 0',
]);

$output = $browser->script('return window.location.pathname');

擷取螢幕截圖

您可以使用 screenshot 方法擷取螢幕截圖並以給定的檔名儲存。所有螢幕截圖都將儲存於 tests/Browser/screenshots 目錄中：

$browser->screenshot('filename');

responsiveScreenshots 方法可用於在各種斷點處擷取一系列螢幕截圖：

$browser->responsiveScreenshots('filename');

screenshotElement 方法可用於擷取頁面上特定元素的螢幕截圖：

$browser->screenshotElement('#selector', 'filename');

將主控台輸出儲存到磁碟

您可以使用 storeConsoleLog 方法將當前瀏覽器的主控台輸出以給定的檔名寫入磁碟。主控台輸出將儲存於 tests/Browser/console 目錄中：

$browser->storeConsoleLog('filename');

將頁面原始碼儲存到磁碟

您可以使用 storeSource 方法將當前頁面的原始碼以給定的檔名寫入磁碟。頁面原始碼將儲存於 tests/Browser/source 目錄中：

$browser->storeSource('filename');

與元素互動

Dusk 選擇器

選擇好的 CSS 選擇器來與元素互動是編寫 Dusk 測試中最困難的部分之一。隨著時間的推移，前端的變更可能會導致以下 CSS 選擇器使您的測試失敗：

// HTML...

<button>Login</button>

// Test...

$browser->click('.login-page .container div > button');

Dusk 選擇器讓您可以專注於編寫有效的測試，而不是記住 CSS 選擇器。要定義一個選擇器，請在您的 HTML 元素中加入 dusk 屬性。然後，當與 Dusk 瀏覽器互動時，在選擇器前加上 @ 即可在測試中操作該附加的元素：

// HTML...

<button dusk="login-button">Login</button>

// Test...

$browser->click('@login-button');

如果需要，您可以透過 selectorHtmlAttribute 方法自訂 Dusk 選擇器所使用的 HTML 屬性。通常，此方法應在應用程式的 AppServiceProvider 的 boot 方法中呼叫：

use Laravel\Dusk\Dusk;

Dusk::selectorHtmlAttribute('data-dusk');

文字、值與屬性

擷取與設定值

Dusk 提供多種方法來與頁面上元素的當前值、顯示文字和屬性互動。例如，要獲取符合給定 CSS 或 Dusk 選擇器的元素的「值」，請使用 value 方法：

// Retrieve the value...
$value = $browser->value('selector');

// Set the value...
$browser->value('selector', 'value');

您可以使用 inputValue 方法來獲取具有給定欄位名稱的輸入元素的「值」：

$value = $browser->inputValue('field');

擷取文字

text 方法可用於擷取符合給定選擇器元素的顯示文字：

$text = $browser->text('selector');

擷取屬性

最後，attribute 方法可用於擷取符合給定選擇器元素的屬性值：

$attribute = $browser->attribute('selector', 'value');

與表單互動

輸入值

Dusk 提供多種方法用於與表單和輸入元素互動。首先，讓我們看看一個將文字輸入到輸入欄位的範例：

$browser->type('email', '[email protected]');

請注意，雖然該方法在必要時接受一個參數，但我們不需要將 CSS 選擇器傳遞給 type 方法。如果未提供 CSS 選擇器，Dusk 將會搜尋具有給定 name 屬性的 input 或 textarea 欄位。

要將文字附加到欄位而不清除其內容，您可以使用 append 方法：

$browser->type('tags', 'foo')
    ->append('tags', ', bar, baz');

您可以使用 clear 方法清除輸入的值：

$browser->clear('email');

您可以指示 Dusk 使用 typeSlowly 方法緩慢輸入。預設情況下，Dusk 會在按鍵之間暫停 100 毫秒。要自訂按鍵之間的暫停時間，您可以將適當的毫秒數作為第三個引數傳遞給該方法：

$browser->typeSlowly('mobile', '+1 (202) 555-5555');

$browser->typeSlowly('mobile', '+1 (202) 555-5555', 300);

您可以使用 appendSlowly 方法緩慢地附加文字：

$browser->type('tags', 'foo')
    ->appendSlowly('tags', ', bar, baz');

下拉選單

要選取 select 元素上可用的值，您可以使用 select 方法。與 type 方法一樣，select 方法不需要完整的 CSS 選擇器。當將值傳遞給 select 方法時，您應該傳遞底層選項值而不是顯示文字：

$browser->select('size', 'Large');

您可以透過省略第二個引數來選取一個隨機選項：

$browser->select('size');

透過提供陣列作為 select 方法的第二個引數，您可以指示該方法選取多個選項：

$browser->select('categories', ['Art', 'Music']);

核取方塊

要「勾選」核取方塊輸入，您可以使用 check 方法。與許多其他輸入相關方法一樣，不需要完整的 CSS 選擇器。如果找不到 CSS 選擇器匹配項，Dusk 將搜尋具有匹配 name 屬性的核取方塊：

$browser->check('terms');

uncheck 方法可用於「取消勾選」核取方塊輸入：

$browser->uncheck('terms');

選項按鈕

要「選取」radio 輸入選項，您可以使用 radio 方法。與許多其他輸入相關方法一樣，不需要完整的 CSS 選擇器。如果找不到 CSS 選擇器匹配項，Dusk 將搜尋具有匹配 name 和 value 屬性的 radio 輸入：

$browser->radio('size', 'large');

附加檔案

attach 方法可用於將檔案附加到 file 輸入元素。與許多其他輸入相關方法一樣，不需要完整的 CSS 選擇器。如果找不到 CSS 選擇器匹配項，Dusk 將搜尋具有匹配 name 屬性的 file 輸入：

$browser->attach('photo', __DIR__.'/photos/mountains.png');

⚠️ 警告

attach 函數要求您的伺服器已安裝並啟用 Zip PHP 擴充功能。

按下按鈕

press 方法可用於點擊頁面上的按鈕元素。傳遞給 press 方法的引數可以是按鈕的顯示文字或 CSS / Dusk 選擇器：

$browser->press('Login');

提交表單時，許多應用程式會在按下表單的提交按鈕後將其停用，然後在表單提交的 HTTP 請求完成後重新啟用該按鈕。要按下按鈕並等待按鈕重新啟用，您可以使用 pressAndWaitFor 方法：

// Press the button and wait a maximum of 5 seconds for it to be enabled...
$browser->pressAndWaitFor('Save');

// Press the button and wait a maximum of 1 second for it to be enabled...
$browser->pressAndWaitFor('Save', 1);

點擊連結

要點擊連結，您可以在瀏覽器實例上使用 clickLink 方法。clickLink 方法將點擊具有給定顯示文字的連結：

$browser->clickLink($linkText);

您可以使用 seeLink 方法來判斷頁面上是否顯示具有給定顯示文字的連結：

if ($browser->seeLink($linkText)) {
    // ...
}

⚠️ 警告

這些方法與 jQuery 互動。如果頁面上沒有 jQuery，Dusk 將會自動將其注入頁面，以便在測試期間可用。

使用鍵盤

keys 方法允許您向給定元素提供比 type 方法通常允許的更複雜的輸入序列。例如，您可以指示 Dusk 在輸入值時按住修飾鍵。在這個範例中，當 taylor 輸入到符合給定選擇器的元素時，shift 鍵將被按住。在輸入 taylor 後，將在不帶任何修飾鍵的情況下輸入 swift：

$browser->keys('selector', ['{shift}', 'taylor'], 'swift');

keys 方法的另一個有價值的用途是將「鍵盤快捷鍵」組合傳送給應用程式的主要 CSS 選擇器：

$browser->keys('.app', ['{command}', 'j']);

📌 備註

所有修飾鍵，例如 {command}，都用 {} 字元包圍，並與 Facebook\WebDriver\WebDriverKeys 類別中定義的常數相符，該類別可在 GitHub 上找到。

流暢的鍵盤互動

Dusk 也提供 withKeyboard 方法，讓您能透過 Laravel\Dusk\Keyboard 類別流暢地執行複雜的鍵盤互動。Keyboard 類別提供了 press、release、type 和 pause 方法：

use Laravel\Dusk\Keyboard;

$browser->withKeyboard(function (Keyboard $keyboard) {
    $keyboard->press('c')
        ->pause(1000)
        ->release('c')
        ->type(['c', 'e', 'o']);
});

鍵盤巨集

如果您想定義可在測試套件中重複使用的自訂鍵盤互動，您可以使用 Keyboard 類別提供的 macro 方法。通常，您應該從服務提供者 (service provider) 的 boot 方法中呼叫此方法：

<?php

namespace App\Providers;

use Facebook\WebDriver\WebDriverKeys;
use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Keyboard;
use Laravel\Dusk\OperatingSystem;

class DuskServiceProvider extends ServiceProvider
{
    /**
     * Register Dusk's browser macros.
     */
    public function boot(): void
    {
        Keyboard::macro('copy', function (string $element = null) {
            $this->type([
                OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'c',
            ]);

            return $this;
        });

        Keyboard::macro('paste', function (string $element = null) {
            $this->type([
                OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'v',
            ]);

            return $this;
        });
    }
}

macro 函數接受一個名稱作為第一個引數，一個閉包作為第二個引數。當作為 Keyboard 實例上的方法呼叫巨集時，巨集的閉包將被執行：

$browser->click('@textarea')
    ->withKeyboard(fn (Keyboard $keyboard) => $keyboard->copy())
    ->click('@another-textarea')
    ->withKeyboard(fn (Keyboard $keyboard) => $keyboard->paste());

使用滑鼠

點擊元素

click 方法可用於點擊符合給定 CSS 或 Dusk 選擇器的元素：

$browser->click('.selector');

clickAtXPath 方法可用於點擊符合給定 XPath 運算式的元素：

$browser->clickAtXPath('//div[@class = "selector"]');

clickAtPoint 方法可用於點擊瀏覽器可視區域內給定座標對處的最頂層元素：

$browser->clickAtPoint($x = 0, $y = 0);

doubleClick 方法可用於模擬滑鼠的雙擊：

$browser->doubleClick();

$browser->doubleClick('.selector');

rightClick 方法可用於模擬滑鼠的右鍵點擊：

$browser->rightClick();

$browser->rightClick('.selector');

clickAndHold 方法可用於模擬滑鼠按鈕被點擊並按住。隨後呼叫 releaseMouse 方法將撤銷此行為並釋放滑鼠按鈕：

$browser->clickAndHold('.selector');

$browser->clickAndHold()
    ->pause(1000)
    ->releaseMouse();

controlClick 方法可用於模擬瀏覽器中的 ctrl+click 事件：

$browser->controlClick();

$browser->controlClick('.selector');

滑鼠懸停

當您需要將滑鼠移到符合給定 CSS 或 Dusk 選擇器的元素上方時，可以使用 mouseover 方法：

$browser->mouseover('.selector');

拖曳

drag 方法可用於將符合給定選擇器的元素拖曳到另一個元素：

$browser->drag('.from-selector', '.to-selector');

或者，您可以將元素沿單一方向拖曳：

$browser->dragLeft('.selector', $pixels = 10);
$browser->dragRight('.selector', $pixels = 10);
$browser->dragUp('.selector', $pixels = 10);
$browser->dragDown('.selector', $pixels = 10);

最後，您可以按給定偏移量拖曳元素：

$browser->dragOffset('.selector', $x = 10, $y = 10);

JavaScript 對話框

Dusk 提供了多種與 JavaScript 對話框互動的方法。例如，您可以使用 waitForDialog 方法等待 JavaScript 對話框出現。此方法接受一個選用引數，指示等待對話框出現的秒數：

$browser->waitForDialog($seconds = null);

assertDialogOpened 方法可用於斷言對話框已顯示並包含給定的訊息：

$browser->assertDialogOpened('Dialog message');

如果 JavaScript 對話框包含提示，您可以使用 typeInDialog 方法在提示中輸入值：

$browser->typeInDialog('Hello World');

要透過點擊「確定」按鈕來關閉開啟的 JavaScript 對話框，您可以呼叫 acceptDialog 方法：

$browser->acceptDialog();

要透過點擊「取消」按鈕來關閉開啟的 JavaScript 對話框，您可以呼叫 dismissDialog 方法：

$browser->dismissDialog();

與內嵌框架互動

如果您需要與 iframe 中的元素互動，可以使用 withinFrame 方法。所有在提供給 withinFrame 方法的閉包中發生的元素互動，都將被限定在指定 iframe 的上下文中：

$browser->withinFrame('#credit-card-details', function ($browser) {
    $browser->type('input[name="cardnumber"]', '4242424242424242')
        ->type('input[name="exp-date"]', '1224')
        ->type('input[name="cvc"]', '123')
        ->press('Pay');
});

範圍化選擇器

有時您可能希望在給定選擇器內執行多個操作。例如，您可能希望斷言某個文字只存在於表格中，然後點擊該表格中的按鈕。您可以使用 with 方法來實現此目的。在提供給 with 方法的閉包中執行的所有操作都將被限定在原始選擇器範圍內：

$browser->with('.table', function (Browser $table) {
    $table->assertSee('Hello World')
        ->clickLink('Delete');
});

您可能偶爾需要在當前範圍之外執行斷言。您可以使用 elsewhere 和 elsewhereWhenAvailable 方法來實現此目的：

 $browser->with('.table', function (Browser $table) {
    // 當前範圍是 `body .table`...

    $browser->elsewhere('.page-title', function (Browser $title) {
        // 當前範圍是 `body .page-title`...
        $title->assertSee('Hello World');
    });

    $browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
        // 當前範圍是 `body .page-title`...
        $title->assertSee('Hello World');
    });
 });

等待元素

測試大量使用 JavaScript 的應用程式時，在繼續測試之前，通常需要「等待」特定的元素或資料可用。Dusk 讓這變得輕而易舉。透過多種方法，您可以等待元素在頁面上可見，甚至等到給定的 JavaScript 表達式評估為 true。

等待

如果您只需要讓測試暫停特定的毫秒數，請使用 pause 方法：

$browser->pause(1000);

如果您只需要在給定條件為 true 時暫停測試，請使用 pauseIf 方法：

$browser->pauseIf(App::environment('production'), 1000);

同樣地，如果您需要在給定條件不為 true 時暫停測試，您可以使用 pauseUnless 方法：

$browser->pauseUnless(App::environment('testing'), 1000);

等待選擇器

waitFor 方法可用來暫停測試執行，直到頁面上顯示出符合指定 CSS 或 Dusk 選擇器的元素。預設情況下，這將使測試暫停最多五秒，然後才會拋出例外。如有必要，您可以將自訂逾時閾值作為方法的第二個引數傳遞：

// 最多等待五秒以獲取選擇器...
$browser->waitFor('.selector');

// 最多等待一秒以獲取選擇器...
$browser->waitFor('.selector', 1);

您也可以等待直到符合指定選擇器的元素包含指定的文字：

// 最多等待五秒以使選擇器包含指定文字...
$browser->waitForTextIn('.selector', 'Hello World');

// 最多等待一秒以使選擇器包含指定文字...
$browser->waitForTextIn('.selector', 'Hello World', 1);

您也可以等到符合指定選擇器的元素從頁面中消失：

// 最多等待五秒直到選擇器消失...
$browser->waitUntilMissing('.selector');

// 最多等待一秒直到選擇器消失...
$browser->waitUntilMissing('.selector', 1);

或者，您也可以等待直到符合指定選擇器的元素被啟用或停用：

// 最多等待五秒直到選擇器被啟用...
$browser->waitUntilEnabled('.selector');

// 最多等待一秒直到選擇器被啟用...
$browser->waitUntilEnabled('.selector', 1);

// 最多等待五秒直到選擇器被停用...
$browser->waitUntilDisabled('.selector');

// 最多等待一秒直到選擇器被停用...
$browser->waitUntilDisabled('.selector', 1);

選擇器可用時的範圍化

有時，您可能希望等待符合指定選擇器的元素出現，然後與該元素互動。例如，您可能希望等到模態視窗可用，然後在該模態視窗中按下「OK」按鈕。whenAvailable 方法可用來達成此目的。在給定閉包中執行的所有元素操作都將範圍化到原始選擇器：

$browser->whenAvailable('.modal', function (Browser $modal) {
    $modal->assertSee('Hello World')
        ->press('OK');
});

等待文字

waitForText 方法可用來等待直到頁面上顯示出指定的文字：

// 最多等待五秒以獲取文字...
$browser->waitForText('Hello World');

// 最多等待一秒以獲取文字...
$browser->waitForText('Hello World', 1);

您可以使用 waitUntilMissingText 方法來等待直到顯示的文字從頁面中移除：

// 最多等待五秒以使文字被移除...
$browser->waitUntilMissingText('Hello World');

// 最多等待一秒以使文字被移除...
$browser->waitUntilMissingText('Hello World', 1);

等待連結

waitForLink 方法可用來等待直到頁面上顯示出指定的連結文字：

// 最多等待五秒以獲取連結...
$browser->waitForLink('Create');

// 最多等待一秒以獲取連結...
$browser->waitForLink('Create', 1);

等待輸入

waitForInput 方法可用來等待直到頁面上顯示出指定的輸入欄位：

// 最多等待五秒以獲取輸入...
$browser->waitForInput($field);

// 最多等待一秒以獲取輸入...
$browser->waitForInput($field, 1);

等待頁面位置

當進行路徑斷言，例如 $browser->assertPathIs('/home') 時，如果 window.location.pathname 正在非同步更新，該斷言可能會失敗。您可以使用 waitForLocation 方法來等待位置成為給定值：

$browser->waitForLocation('/secret');

waitForLocation 方法也可用來等待目前視窗位置成為完整的 URL：

$browser->waitForLocation('https://example.com/path');

您也可以等待 命名路由 的位置：

$browser->waitForRoute($routeName, $parameters);

等待頁面重新載入

如果您需要在執行某個動作後等待頁面重新載入，請使用 waitForReload 方法：

use Laravel\Dusk\Browser;

$browser->waitForReload(function (Browser $browser) {
    $browser->press('Submit');
})
->assertSee('Success!');

由於等待頁面重新載入的需求通常發生在點擊按鈕之後，為了方便起見，您可以使用 clickAndWaitForReload 方法：

$browser->clickAndWaitForReload('.selector')
    ->assertSee('something');

等待 JavaScript 表達式

有時，您可能希望暫停測試執行，直到給定的 JavaScript 表達式評估為 true。您可以使用 waitUntil 方法輕鬆達成此目的。當向此方法傳遞表達式時，您不需要包含 return 關鍵字或結尾分號：

// 最多等待五秒以使表達式為 true...
$browser->waitUntil('App.data.servers.length > 0');

// 最多等待一秒以使表達式為 true...
$browser->waitUntil('App.data.servers.length > 0', 1);

等待 Vue 表達式

waitUntilVue 和 waitUntilVueIsNot 方法可用來等待直到 Vue component 屬性具有給定值：

// 等待直到元件屬性包含給定值...
$browser->waitUntilVue('user.name', 'Taylor', '@user');

// 等待直到元件屬性不包含給定值...
$browser->waitUntilVueIsNot('user.name', null, '@user');

等待 JavaScript 事件

waitForEvent 方法可用來暫停測試執行，直到 JavaScript 事件發生：

$browser->waitForEvent('load');

事件監聽器預設會附加到目前作用域，即 body 元素。當使用範圍化選擇器時，事件監聽器將會附加到匹配的元素：

$browser->with('iframe', function (Browser $iframe) {
    // 等待 iframe 的載入事件...
    $iframe->waitForEvent('load');
});

您也可以提供選擇器作為 waitForEvent 方法的第二個引數，以將事件監聽器附加到特定元素：

$browser->waitForEvent('load', '.selector');

您也可以等待 document 和 window 物件上的事件：

// 等待直到 document 被捲動...
$browser->waitForEvent('scroll', 'document');

// 最多等待五秒直到 window 被調整大小...
$browser->waitForEvent('resize', 'window', 5);

使用回呼等待

Dusk 中的許多「等待」方法都依賴於底層的 waitUsing 方法。您可以直接使用此方法來等待給定的閉包傳回 true。waitUsing 方法接受最大等待秒數、評估閉包的間隔、閉包本身，以及可選的失敗訊息：

$browser->waitUsing(10, 1, function () use ($something) {
    return $something->isReady();
}, "Something wasn't ready in time.");

將元素捲動到檢視區

有時候您可能無法點擊某個元素，因為它在瀏覽器的可視區域之外。scrollIntoView 方法將會捲動瀏覽器視窗，直到給定選擇器所指定的元素進入檢視區為止：

$browser->scrollIntoView('.selector')
    ->click('.selector');

可用的斷言

Dusk 提供了多種可對應用程式進行的斷言。所有可用的斷言都記錄在下方列表中：

assertTitleassertTitleContainsassertUrlIsassertSchemeIsassertSchemeIsNotassertHostIsassertHostIsNotassertPortIsassertPortIsNotassertPathBeginsWithassertPathEndsWithassertPathContainsassertPathIsassertPathIsNotassertRouteIsassertQueryStringHasassertQueryStringMissingassertFragmentIsassertFragmentBeginsWithassertFragmentIsNotassertHasCookieassertHasPlainCookieassertCookieMissingassertPlainCookieMissingassertCookieValueassertPlainCookieValueassertSeeassertDontSeeassertSeeInassertDontSeeInassertSeeAnythingInassertSeeNothingInassertScriptassertSourceHasassertSourceMissingassertSeeLinkassertDontSeeLinkassertInputValueassertInputValueIsNotassertCheckedassertNotCheckedassertIndeterminateassertRadioSelectedassertRadioNotSelectedassertSelectedassertNotSelectedassertSelectHasOptionsassertSelectMissingOptionsassertSelectHasOptionassertSelectMissingOptionassertValueassertValueIsNotassertAttributeassertAttributeMissingassertAttributeContainsassertAttributeDoesntContainassertAriaAttributeassertDataAttributeassertVisibleassertPresentassertNotPresentassertMissingassertInputPresentassertInputMissingassertDialogOpenedassertEnabledassertDisabledassertButtonEnabledassertButtonDisabledassertFocusedassertNotFocusedassertAuthenticatedassertGuestassertAuthenticatedAsassertVueassertVueIsNotassertVueContainsassertVueDoesntContain

assertTitle

斷言頁面標題與給定的文字相符：

$browser->assertTitle($title);

assertTitleContains

斷言頁面標題包含給定的文字：

$browser->assertTitleContains($title);

assertUrlIs

斷言目前 URL (不含查詢字串) 與給定的字串相符：

$browser->assertUrlIs($url);

assertSchemeIs

斷言目前 URL 方案 (scheme) 與給定的方案相符：

$browser->assertSchemeIs($scheme);

assertSchemeIsNot

斷言目前 URL 方案 (scheme) 與給定的方案不相符：

$browser->assertSchemeIsNot($scheme);

assertHostIs

斷言目前 URL 主機與給定的主機相符：

$browser->assertHostIs($host);

assertHostIsNot

斷言目前 URL 主機與給定的主機不相符：

$browser->assertHostIsNot($host);

assertPortIs

斷言目前 URL 埠號與給定的埠號相符：

$browser->assertPortIs($port);

assertPortIsNot

斷言目前 URL 埠號與給定的埠號不相符：

$browser->assertPortIsNot($port);

assertPathBeginsWith

斷言目前 URL 路徑以給定的路徑開頭：

$browser->assertPathBeginsWith('/home');

assertPathEndsWith

斷言目前 URL 路徑以給定的路徑結尾：

$browser->assertPathEndsWith('/home');

assertPathContains

斷言目前 URL 路徑包含給定的路徑：

$browser->assertPathContains('/home');

assertPathIs

斷言目前路徑與給定的路徑相符：

$browser->assertPathIs('/home');

assertPathIsNot

斷言目前路徑與給定的路徑不相符：

$browser->assertPathIsNot('/home');

assertRouteIs

斷言目前 URL 與給定的 具名路由 的 URL 相符：

$browser->assertRouteIs($name, $parameters);

assertQueryStringHas

斷言給定的查詢字串參數存在：

$browser->assertQueryStringHas($name);

斷言給定的查詢字串參數存在並具有給定的值：

$browser->assertQueryStringHas($name, $value);

assertQueryStringMissing

斷言給定的查詢字串參數不存在：

$browser->assertQueryStringMissing($name);

assertFragmentIs

斷言 URL 的目前雜湊片段與給定的片段相符：

$browser->assertFragmentIs('anchor');

assertFragmentBeginsWith

斷言 URL 的目前雜湊片段以給定的片段開頭：

$browser->assertFragmentBeginsWith('anchor');

assertFragmentIsNot

斷言 URL 的目前雜湊片段與給定的片段不相符：

$browser->assertFragmentIsNot('anchor');

assertHasCookie

斷言給定的加密 cookie 存在：

$browser->assertHasCookie($name);

assertHasPlainCookie

斷言給定的未加密 cookie 存在：

$browser->assertHasPlainCookie($name);

assertCookieMissing

斷言給定的加密 cookie 不存在：

$browser->assertCookieMissing($name);

assertPlainCookieMissing

斷言給定的未加密 cookie 不存在：

$browser->assertPlainCookieMissing($name);

assertCookieValue

斷言加密 cookie 具有給定的值：

$browser->assertCookieValue($name, $value);

assertPlainCookieValue

斷言一個未加密的 Cookie 具有給定的值：

$browser->assertPlainCookieValue($name, $value);

assertSee

斷言頁面上存在給定的文字：

$browser->assertSee($text);

assertDontSee

斷言頁面上不存在給定的文字：

$browser->assertDontSee($text);

assertSeeIn

斷言選擇器中存在給定的文字：

$browser->assertSeeIn($selector, $text);

assertDontSeeIn

斷言選擇器中不存在給定的文字：

$browser->assertDontSeeIn($selector, $text);

assertSeeAnythingIn

斷言選擇器中存在任何文字：

$browser->assertSeeAnythingIn($selector);

assertSeeNothingIn

斷言選擇器中不存在任何文字：

$browser->assertSeeNothingIn($selector);

assertScript

斷言給定的 JavaScript 表達式評估為給定的值：

$browser->assertScript('window.isLoaded')
        ->assertScript('document.readyState', 'complete');

assertSourceHas

斷言頁面中存在給定的原始碼：

$browser->assertSourceHas($code);

assertSourceMissing

斷言頁面中不存在給定的原始碼：

$browser->assertSourceMissing($code);

assertSeeLink

斷言頁面上存在給定的連結：

$browser->assertSeeLink($linkText);

assertDontSeeLink

斷言頁面上不存在給定的連結：

$browser->assertDontSeeLink($linkText);

assertInputValue

斷言給定的輸入欄位具有給定的值：

$browser->assertInputValue($field, $value);

assertInputValueIsNot

斷言給定的輸入欄位不具有給定的值：

$browser->assertInputValueIsNot($field, $value);

assertChecked

斷言給定的核取方塊已勾選：

$browser->assertChecked($field);

assertNotChecked

斷言給定的核取方塊未勾選：

$browser->assertNotChecked($field);

assertIndeterminate

斷言給定的核取方塊處於不確定狀態：

$browser->assertIndeterminate($field);

assertRadioSelected

斷言給定的單選欄位已選取：

$browser->assertRadioSelected($field, $value);

assertRadioNotSelected

斷言給定的單選欄位未選取：

$browser->assertRadioNotSelected($field, $value);

assertSelected

斷言給定的下拉選單已選取給定的值：

$browser->assertSelected($field, $value);

assertNotSelected

斷言給定的下拉選單未選取給定的值：

$browser->assertNotSelected($field, $value);

assertSelectHasOptions

斷言給定的值陣列可供選取：

$browser->assertSelectHasOptions($field, $values);

assertSelectMissingOptions

斷言給定的值陣列不可供選取：

$browser->assertSelectMissingOptions($field, $values);

assertSelectHasOption

斷言給定的值可供給定欄位選取：

$browser->assertSelectHasOption($field, $value);

assertSelectMissingOption

斷言給定的值不可供選取：

$browser->assertSelectMissingOption($field, $value);

assertValue

斷言符合給定選擇器的元素具有給定的值：

$browser->assertValue($selector, $value);

assertValueIsNot

斷言符合給定選擇器的元素不具有給定的值：

$browser->assertValueIsNot($selector, $value);

assertAttribute

斷言符合給定選擇器的元素在提供的屬性中具有給定的值：

$browser->assertAttribute($selector, $attribute, $value);

assertAttributeMissing

斷言符合給定選擇器的元素遺失提供的屬性：

$browser->assertAttributeMissing($selector, $attribute);

assertAttributeContains

斷言符合給定選擇器的元素在提供的屬性中包含給定的值：

$browser->assertAttributeContains($selector, $attribute, $value);

assertAttributeDoesntContain

斷言符合給定選擇器的元素在提供的屬性中不包含給定的值：

$browser->assertAttributeDoesntContain($selector, $attribute, $value);

assertAriaAttribute

斷言符合給定選擇器的元素在提供的 aria 屬性中具有給定的值：

$browser->assertAriaAttribute($selector, $attribute, $value);

例如，給定標記 <button aria-label="Add"></button>，您可以像這樣斷言 aria-label 屬性：

$browser->assertAriaAttribute('button', 'label', 'Add')

assertDataAttribute

斷言符合給定選擇器的元素在提供的 data 屬性中具有給定的值：

$browser->assertDataAttribute($selector, $attribute, $value);

例如，給定標記 <tr id="row-1" data-content="attendees"></tr>，您可以像這樣斷言 data-label 屬性：

$browser->assertDataAttribute('#row-1', 'content', 'attendees')

assertVisible

斷言符合給定選擇器的元素可見：

$browser->assertVisible($selector);

assertPresent

斷言符合給定選擇器的元素存在於原始碼中：

$browser->assertPresent($selector);

assertNotPresent

斷言符合給定選擇器的元素不存在於原始碼中：

$browser->assertNotPresent($selector);

assertMissing

斷言符合給定選擇器的元素不可見：

$browser->assertMissing($selector);

assertInputPresent

斷言存在具有給定名稱的輸入：

$browser->assertInputPresent($name);

assertInputMissing

斷言原始碼中不存在具有給定名稱的輸入：

$browser->assertInputMissing($name);

assertDialogOpened

斷言已開啟具有給定訊息的 JavaScript 對話框：

$browser->assertDialogOpened($message);

assertEnabled

斷言給定的欄位已啟用：

$browser->assertEnabled($field);

assertDisabled

斷言給定的欄位已停用：

$browser->assertDisabled($field);

assertButtonEnabled

斷言給定的按鈕已啟用：

$browser->assertButtonEnabled($button);

assertButtonDisabled

斷言給定的按鈕已停用：

$browser->assertButtonDisabled($button);

assertFocused

確認指定的欄位已獲取焦點：

$browser->assertFocused($field);

assertNotFocused

確認指定的欄位未獲取焦點：

$browser->assertNotFocused($field);

assertAuthenticated

確認使用者已通過身份驗證：

$browser->assertAuthenticated();

assertGuest

確認使用者未通過身份驗證：

$browser->assertGuest();

assertAuthenticatedAs

確認使用者已以指定的使用者身份通過身份驗證：

$browser->assertAuthenticatedAs($user);

assertVue

Dusk 甚至允許您對 Vue component 資料的狀態進行斷言。舉例來說，假設您的應用程式包含以下 Vue component：

// HTML...

<profile dusk="profile-component"></profile>

// Component Definition...

Vue.component('profile', {
    template: '<div>{{ user.name }}</div>',

    data: function () {
        return {
            user: {
                name: 'Taylor'
            }
        };
    }
});

您可以對 Vue component 的狀態進行斷言，如下所示：

Pest

test('vue', function () {
    $this->browse(function (Browser $browser) {
        $browser->visit('/')
            ->assertVue('user.name', 'Taylor', '@profile-component');
    });
});

PHPUnit

/**
 * A basic Vue test example.
 */
public function test_vue(): void
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/')
            ->assertVue('user.name', 'Taylor', '@profile-component');
    });
}

assertVueIsNot

確認指定的 Vue component 資料屬性與指定的值不符：

$browser->assertVueIsNot($property, $value, $componentSelector = null);

assertVueContains

確認指定的 Vue component 資料屬性是一個陣列且包含指定的值：

$browser->assertVueContains($property, $value, $componentSelector = null);

assertVueDoesntContain

確認指定的 Vue component 資料屬性是一個陣列且不包含指定的值：

$browser->assertVueDoesntContain($property, $value, $componentSelector = null);

頁面

有時候，測試需要依序執行多個複雜動作。這會讓你的測試變得難以閱讀和理解。Dusk Pages (頁面) 允許你定義表達性動作，然後透過單一方法在特定頁面上執行。頁面也允許你為應用程式或單一頁面定義常用選擇器的快捷方式。

產生頁面

要產生一個頁面物件，請執行 dusk:page Artisan 命令。所有頁面物件都將放置在你的應用程式的 tests/Browser/Pages 目錄中：

php artisan dusk:page Login

配置頁面

預設情況下，頁面有三個方法：url、assert 和 elements。我們現在將討論 url 和 assert 方法。elements 方法將在下面更詳細地討論。

url 方法

url 方法應該回傳代表該頁面的 URL 路徑。Dusk 會在瀏覽器中導覽至該頁面時使用此 URL：

/**
 * Get the URL for the page.
 */
public function url(): string
{
    return '/login';
}

assert 方法

assert 方法可以進行任何必要的斷言，以驗證瀏覽器確實位於指定頁面。實際上不需要在此方法中放置任何內容；但是，如果你願意，可以自由地進行這些斷言。這些斷言會在導覽至頁面時自動執行：

/**
 * Assert that the browser is on the page.
 */
public function assert(Browser $browser): void
{
    $browser->assertPathIs($this->url());
}

導覽至頁面

一旦定義了頁面，你就可以使用 visit 方法導覽到它：

use Tests\Browser\Pages\Login;

$browser->visit(new Login);

有時候你可能已經在某個頁面上，需要將該頁面的選擇器和方法「載入」到目前的測試上下文中。這在按下按鈕並被重新導向到指定頁面而沒有明確導覽到該頁面時很常見。在這種情況下，你可以使用 on 方法來載入頁面：

use Tests\Browser\Pages\CreatePlaylist;

$browser->visit('/dashboard')
        ->clickLink('Create Playlist')
        ->on(new CreatePlaylist)
        ->assertSee('@create');

縮寫選擇器

頁面類別中的 elements 方法允許你為頁面上的任何 CSS 選擇器定義快速、易於記憶的快捷方式。例如，讓我們為應用程式登入頁面中的「email」輸入欄位定義一個快捷方式：

/**
 * Get the element shortcuts for the page.
 *
 * @return array<string, string>
 */
public function elements(): array
{
    return [
        '@email' => 'input[name=email]',
    ];
}

一旦定義了快捷方式，你就可以在任何通常會使用完整 CSS 選擇器的地方使用該縮寫選擇器：

$browser->type('@email', '[email protected]');

全域縮寫選擇器

安裝 Dusk 後，一個基礎的 Page 類別會被放置在你的 tests/Browser/Pages 目錄中。這個類別包含一個 siteElements 方法，可用於定義應該在應用程式中每個頁面上都可用的全域縮寫選擇器：

/**
 * Get the global element shortcuts for the site.
 *
 * @return array<string, string>
 */
public static function siteElements(): array
{
    return [
        '@element' => '#selector',
    ];
}

頁面方法

除了頁面上定義的預設方法之外，你還可以定義可以在整個測試中使用的額外方法。例如，假設我們正在建立一個音樂管理應用程式。應用程式的某個頁面常見的動作可能是建立一個播放清單。與其在每個測試中重寫建立播放清單的邏輯，不如在頁面類別上定義一個 createPlaylist 方法：

<?php

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;
use Laravel\Dusk\Page;

class Dashboard extends Page
{
    // Other page methods...

    /**
     * Create a new playlist.
     */
    public function createPlaylist(Browser $browser, string $name): void
    {
        $browser->type('name', $name)
            ->check('share')
            ->press('Create Playlist');
    }
}

一旦定義了該方法，你就可以在任何使用該頁面的測試中使用它。瀏覽器實例會自動作為第一個參數傳遞給自訂頁面方法：

use Tests\Browser\Pages\Dashboard;

$browser->visit(new Dashboard)
        ->createPlaylist('My Playlist')
        ->assertSee('My Playlist');

元件

元件類似於 Dusk 的「頁面物件」，但旨在用於應用程式中重複使用的 UI 和功能區塊，例如導覽列或通知視窗。因此，元件不綁定特定 URL。

產生元件

若要產生元件，請執行 dusk:component Artisan 命令。新元件會放置在 tests/Browser/Components 目錄中：

php artisan dusk:component DatePicker

如上所示，「日期選擇器」就是一種可能存在於應用程式中多個頁面的元件範例。在整個測試套件的數十個測試中，手動編寫瀏覽器自動化邏輯來選擇日期可能會變得繁瑣。相反地，我們可以定義一個 Dusk 元件來表示日期選擇器，讓我們能夠將該邏輯封裝在元件中：

<?php

namespace Tests\Browser\Components;

use Laravel\Dusk\Browser;
use Laravel\Dusk\Component as BaseComponent;

class DatePicker extends BaseComponent
{
    /**
     * Get the root selector for the component.
     */
    public function selector(): string
    {
        return '.date-picker';
    }

    /**
     * Assert that the browser page contains the component.
     */
    public function assert(Browser $browser): void
    {
        $browser->assertVisible($this->selector());
    }

    /**
     * Get the element shortcuts for the component.
     *
     * @return array<string, string>
     */
    public function elements(): array
    {
        return [
            '@date-field' => 'input.datepicker-input',
            '@year-list' => 'div > div.datepicker-years',
            '@month-list' => 'div > div.datepicker-months',
            '@day-list' => 'div > div.datepicker-days',
        ];
    }

    /**
     * Select the given date.
     */
    public function selectDate(Browser $browser, int $year, int $month, int $day): void
    {
        $browser->click('@date-field')
            ->within('@year-list', function (Browser $browser) use ($year) {
                $browser->click($year);
            })
            ->within('@month-list', function (Browser $browser) use ($month) {
                $browser->click($month);
            })
            ->within('@day-list', function (Browser $browser) use ($day) {
                $browser->click($day);
            });
    }
}

使用元件

一旦元件被定義，我們就可以在任何測試中輕鬆地從日期選擇器中選擇日期。而且，如果選擇日期所需的邏輯發生變化，我們只需更新該元件即可：

Pest

<?php

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\Browser\Components\DatePicker;

uses(DatabaseMigrations::class);

test('basic example', function () {
    $this->browse(function (Browser $browser) {
        $browser->visit('/')
            ->within(new DatePicker, function (Browser $browser) {
                $browser->selectDate(2019, 1, 30);
            })
            ->assertSee('January');
    });
});

PHPUnit

<?php

namespace Tests\Browser;

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\Browser\Components\DatePicker;
use Tests\DuskTestCase;

class ExampleTest extends DuskTestCase
{
    /**
     * A basic component test example.
     */
    public function test_basic_example(): void
    {
        $this->browse(function (Browser $browser) {
            $browser->visit('/')
                ->within(new DatePicker, function (Browser $browser) {
                    $browser->selectDate(2019, 1, 30);
                })
                ->assertSee('January');
        });
    }
}

持續整合

⚠️ 警告

大多數 Dusk 持續整合配置預期您的 Laravel 應用程式是使用內建的 PHP 開發伺服器在 8000 埠提供服務。因此，在繼續之前，您應該確保您的持續整合環境中 APP_URL 環境變數的值為 http://127.0.0.1:8000。

Heroku CI

要在 Heroku CI 上執行 Dusk 測試，請將以下 Google Chrome buildpack 和腳本添加到您的 Heroku app.json 檔案中：

{
  "environments": {
    "test": {
      "buildpacks": [
        { "url": "heroku/php" },
        { "url": "https://github.com/heroku/heroku-buildpack-chrome-for-testing" }
      ],
      "scripts": {
        "test-setup": "cp .env.testing .env",
        "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux --port=9515 > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
      }
    }
  }
}

Travis CI

要在 Travis CI 上執行您的 Dusk 測試，請使用以下 .travis.yml 配置。由於 Travis CI 不是圖形環境，我們需要採取一些額外的步驟來啟動 Chrome 瀏覽器。此外，我們將使用 php artisan serve 來啟動 PHP 的內建網頁伺服器：

language: php

php:
  - 8.2

addons:
  chrome: stable

install:
  - cp .env.testing .env
  - travis_retry composer install --no-interaction --prefer-dist
  - php artisan key:generate
  - php artisan dusk:chrome-driver

before_script:
  - google-chrome-stable --headless --disable-gpu --remote-debugging-port=9222 http://localhost &
  - php artisan serve --no-reload &

script:
  - php artisan dusk

GitHub Actions

如果您正在使用 GitHub Actions 來執行您的 Dusk 測試，您可以使用以下配置檔案作為起點。與 TravisCI 類似，我們將使用 php artisan serve 命令來啟動 PHP 的內建網頁伺服器：

name: CI
on: [push]
jobs:

  dusk-php:
    runs-on: ubuntu-latest
    env:
      APP_URL: "http://127.0.0.1:8000"
      DB_USERNAME: root
      DB_PASSWORD: root
      MAIL_MAILER: log
    steps:
      - uses: actions/checkout@v4
      - name: Prepare The Environment
        run: cp .env.example .env
      - name: Create Database
        run: |
          sudo systemctl start mysql
          mysql --user="root" --password="root" -e "CREATE DATABASE \`my-database\` character set UTF8mb4 collate utf8mb4_bin;"
      - name: Install Composer Dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader
      - name: Generate Application Key
        run: php artisan key:generate
      - name: Upgrade Chrome Driver
        run: php artisan dusk:chrome-driver --detect
      - name: Start Chrome Driver
        run: ./vendor/laravel/dusk/bin/chromedriver-linux --port=9515 &
      - name: Run Laravel Server
        run: php artisan serve --no-reload &
      - name: Run Dusk Tests
        run: php artisan dusk
      - name: Upload Screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: tests/Browser/screenshots
      - name: Upload Console Logs
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: console
          path: tests/Browser/console

Chipper CI

如果您正在使用 Chipper CI 來執行您的 Dusk 測試，您可以使用以下配置檔案作為起點。我們將使用 PHP 的內建伺服器來執行 Laravel，以便我們可以監聽請求：

# file .chipperci.yml
version: 1

environment:
  php: 8.2
  node: 16

# Include Chrome in the build environment
services:
  - dusk

# Build all commits
on:
   push:
      branches: .*

pipeline:
  - name: Setup
    cmd: |
      cp -v .env.example .env
      composer install --no-interaction --prefer-dist --optimize-autoloader
      php artisan key:generate

      # Create a dusk env file, ensuring APP_URL uses BUILD_HOST
      cp -v .env .env.dusk.ci
      sed -i "s@APP_URL=.*@APP_URL=http://$BUILD_HOST:8000@g" .env.dusk.ci

  - name: Compile Assets
    cmd: |
      npm ci --no-audit
      npm run build

  - name: Browser Tests
    cmd: |
      php -S [::0]:8000 -t public 2>server.log &
      sleep 2
      php artisan dusk:chrome-driver $CHROME_DRIVER
      php artisan dusk --env=ci

要了解更多關於在 Chipper CI 上執行 Dusk 測試的資訊，包括如何使用資料庫，請查閱 官方 Chipper CI 文件。