Laravel Dusk

簡介
安裝
- 安裝 ChromeDriver
- 使用其他瀏覽器
入門
「Browser」基礎
與元素互動
可用的 Assertion
Page
Component (元件)
- 產生 Component
- 使用 Component
持續整合 (Continuous Integration)

簡介

Laravel Dusk 提供了一個豐富、簡單易用的瀏覽器自動化與測試 API。預設情況下，使用 Dusk 不需要額外在本機電腦上安裝 JDK 或 Slenium。Dusk 會使用獨立的 ChromeDriver 安裝。不過，也可以自由使用其他 Selenium 相容的驅動器。

安裝

要開始使用 Dusk，請先安裝 Google Chrome，並將 laravel/dusk Composer 相依性套件加到專案中：

1composer require --dev laravel/dusk1composer require --dev laravel/dusk

若要手動註冊 Dusk 的 Service Provider，請不要在正式環境內加上該 Provider，因為這麼會讓所有人都能任意登入任何使用者。

安裝好 Dusk 套件後，請執行 dusk:install Artisan 指令。dusk:install 指令會建立 tests/Browser 資料夾，以及一個 Dusk 範例測試：

1php artisan dusk:install1php artisan dusk:install

接著，請在專案的 .env 檔內設定 APP_URL 環境變數。該變數應符合要在瀏覽器內存取專案的 URL。

若使用 Laravel Sail 來管理本機開發環境，也請一併參考 Sail 說明文件中有關設定與執行 Dusk 測試的部分。

管理 ChromeDriver 安裝

若想安裝與 Laravel Dusk 附帶的 ChromeDriver 不同的版本，可使用 dusk:chrome-driver 指令：

 1# 為你的作業系統安裝最新版的 ChromeDriver...
 2php artisan dusk:chrome-driver
 3 
 4# 為你的作業系統安裝給定版本的 ChromeDriver...
 5php artisan dusk:chrome-driver 86
 6 
 7# 為所有支援的作業系統安裝最新版的 ChromeDriver...
 8php artisan dusk:chrome-driver --all
 9 
10# 為你的作業系統安裝符合偵測到的 Chrome / Chromium 版本之 ChromeDriver 版本...
11php artisan dusk:chrome-driver --detect 1# 為你的作業系統安裝最新版的 ChromeDriver...
 2php artisan dusk:chrome-driver
 3 
 4# 為你的作業系統安裝給定版本的 ChromeDriver...
 5php artisan dusk:chrome-driver 86
 6 
 7# 為所有支援的作業系統安裝最新版的 ChromeDriver...
 8php artisan dusk:chrome-driver --all
 9 
10# 為你的作業系統安裝符合偵測到的 Chrome / Chromium 版本之 ChromeDriver 版本...
11php 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：

 1/**
 2 * Prepare for Dusk test execution.
 3 *
 4 * @beforeClass
 5 * @return void
 6 */
 7public static function prepare()
 8{
 9    // static::startChromeDriver();
10} 1/**
 2 * Prepare for Dusk test execution.
 3 *
 4 * @beforeClass
 5 * @return void
 6 */
 7public static function prepare()
 8{
 9    // static::startChromeDriver();
10}

接著，可以修改 driver 方法來連先到所選的 URL 與連結埠。另外，也可以修改應傳給 WebDriver 的「Desired Capabilities (所需功能)」：

 1/**
 2 * Create the RemoteWebDriver instance.
 3 *
 4 * @return \Facebook\WebDriver\Remote\RemoteWebDriver
 5 */
 6protected function driver()
 7{
 8    return RemoteWebDriver::create(
 9        'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
10    );
11} 1/**
 2 * Create the RemoteWebDriver instance.
 3 *
 4 * @return \Facebook\WebDriver\Remote\RemoteWebDriver
 5 */
 6protected function driver()
 7{
 8    return RemoteWebDriver::create(
 9        'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
10    );
11}

入門

產生測試

若要產生 Dusk 測試，請使用 dusk:make Artisan 指令。產生的測試將放置於 tests/Browser 目錄內：

1php artisan dusk:make LoginTest1php artisan dusk:make LoginTest

資料庫 Migration

我們所撰寫的大部分的測試所互動的頁面都會從專案的資料庫內取得資料。不過，Dusk 測試不應使用 RefreshDatabase Trait。RefreshDatabase Trait 使用資料庫 Transaction，會讓資料無法在不同 HTTP 請求間共用。請改用 DatabaseMigrations Trait，為每個測試重新 Migrate 資料庫：

 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use App\Models\User;
 6use Illuminate\Foundation\Testing\DatabaseMigrations;
 7use Laravel\Dusk\Chrome;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    use DatabaseMigrations;
13} 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use App\Models\User;
 6use Illuminate\Foundation\Testing\DatabaseMigrations;
 7use Laravel\Dusk\Chrome;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    use DatabaseMigrations;
13}

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

執行測試

若要執行瀏覽器測試，請執行 dusk Artisan 指令：

1php artisan dusk1php artisan dusk

若在上次執行 dusk 指令時有測試失敗了，則可以通過 dusk:fails 指令來先重新執行失敗的測試以節省時間：

1php artisan dusk:fails1php artisan dusk:fails

dusk 指令接受所有一般 PHPUnit 測試執行程式所接受的引數，如可以只執行特定群組內的測試：

1php artisan dusk --group=foo1php artisan dusk --group=foo

若使用 Laravel Sail 來管理本機開發環境，請參考 Sail 說明文件中有關設定與執行 Dusk 測試的部分。

手動啟動 ChromeDriver

預設情況下，Dusk 會自動嘗試開啟 ChromeDriver。若你所使用的系統無法自動開啟 ChromeDriver，則可以在執行 dusk 指令前手動啟動 ChromeDriver。若想手動啟動 ChromeDriver，則應先在 test/DuskTestCase.php 檔中將下列部分註解掉：

 1/**
 2 * Prepare for Dusk test execution.
 3 *
 4 * @beforeClass
 5 * @return void
 6 */
 7public static function prepare()
 8{
 9    // static::startChromeDriver();
10} 1/**
 2 * Prepare for Dusk test execution.
 3 *
 4 * @beforeClass
 5 * @return void
 6 */
 7public static function prepare()
 8{
 9    // static::startChromeDriver();
10}

此外，若在 9515 連結埠以外的其他連結埠上開啟 ChromeDriver，則應在相同類別內修改 driver 方法以修改為相應的連結埠：

 1/**
 2 * Create the RemoteWebDriver instance.
 3 *
 4 * @return \Facebook\WebDriver\Remote\RemoteWebDriver
 5 */
 6protected function driver()
 7{
 8    return RemoteWebDriver::create(
 9        'http://localhost:9515', DesiredCapabilities::chrome()
10    );
11} 1/**
 2 * Create the RemoteWebDriver instance.
 3 *
 4 * @return \Facebook\WebDriver\Remote\RemoteWebDriver
 5 */
 6protected function driver()
 7{
 8    return RemoteWebDriver::create(
 9        'http://localhost:9515', DesiredCapabilities::chrome()
10    );
11}

處理環境

若要在執行測試時強制讓 Dusk 使用自己的環境檔，請在專案根目錄下建立一個 .env.dusk.{environment} 檔案。舉例來說，若會在 local 環境下執行 dusk，請建立 .env.dusk.local 檔案。

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

「瀏覽器」基礎

建立瀏覽器

要開始使用瀏覽器，我們先來建立一個用來認證能否登入網站的測試。產生測試後，我們就可以修改該測試、前往登入頁、輸入帳號密碼、並點擊「登入」按鈕。要建立瀏覽器實體，可在 Dusk 測試內呼叫 browser 方法：

 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use App\Models\User;
 6use Illuminate\Foundation\Testing\DatabaseMigrations;
 7use Laravel\Dusk\Chrome;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    use DatabaseMigrations;
13 
14    /**
15     * A basic browser test example.
16     *
17     * @return void
18     */
19    public function test_basic_example()
20    {
21        $user = User::factory()->create([
22            'email' => '[email protected]',
23        ]);
24 
25        $this->browse(function ($browser) use ($user) {
26            $browser->visit('/login')
27                    ->type('email', $user->email)
28                    ->type('password', 'password')
29                    ->press('Login')
30                    ->assertPathIs('/home');
31        });
32    }
33} 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use App\Models\User;
 6use Illuminate\Foundation\Testing\DatabaseMigrations;
 7use Laravel\Dusk\Chrome;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    use DatabaseMigrations;
13 
14    /**
15     * A basic browser test example.
16     *
17     * @return void
18     */
19    public function test_basic_example()
20    {
21        $user = User::factory()->create([
22            'email' => '[email protected]',
23        ]);
24 
25        $this->browse(function ($browser) use ($user) {
26            $browser->visit('/login')
27                    ->type('email', $user->email)
28                    ->type('password', 'password')
29                    ->press('Login')
30                    ->assertPathIs('/home');
31        });
32    }
33}

如上所見，browser 方法接受一個閉包。Dusk 會自動將瀏覽器實體傳入該閉包內，瀏覽器實體是用來與網站互動以及用來進行 Assertion 的主要物件。

建立多個瀏覽器

有時候，我們需要建立多個瀏覽器來正確地進行測試。舉例來說，在測試與 WebSocket 互動的聊天畫面時可能會需要多個瀏覽器。若要建立多個瀏覽器，只需要將多個瀏覽器引數加到提供給 browser 方法的閉包上即可：

 1$this->browse(function ($first, $second) {
 2    $first->loginAs(User::find(1))
 3          ->visit('/home')
 4          ->waitForText('Message');
 5 
 6    $second->loginAs(User::find(2))
 7           ->visit('/home')
 8           ->waitForText('Message')
 9           ->type('message', 'Hey Taylor')
10           ->press('Send');
11 
12    $first->waitForText('Hey Taylor')
13          ->assertSee('Jeffrey Way');
14}); 1$this->browse(function ($first, $second) {
 2    $first->loginAs(User::find(1))
 3          ->visit('/home')
 4          ->waitForText('Message');
 5 
 6    $second->loginAs(User::find(2))
 7           ->visit('/home')
 8           ->waitForText('Message')
 9           ->type('message', 'Hey Taylor')
10           ->press('Send');
11 
12    $first->waitForText('Hey Taylor')
13          ->assertSee('Jeffrey Way');
14});

visit 方法可用來在網站內導航到特定的 URI 上：

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

可以使用 visitRoute 方法來導航到命名路由：

1$browser->visitRoute('login');1$browser->visitRoute('login');

可以使用 back 與 forward 方法來導航到「上一頁」與「下一頁」：

1$browser->back();
2 
3$browser->forward();1$browser->back();
2 
3$browser->forward();

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

1$browser->refresh();1$browser->refresh();

縮放瀏覽器視窗

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

1$browser->resize(1920, 1080);1$browser->resize(1920, 1080);

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

1$browser->maximize();1$browser->maximize();

fitContent 方法會將瀏覽器視窗縮放到符合其內容的大小：

1$browser->fitContent();1$browser->fitContent();

當測試失敗時，Dusk 會自動縮放瀏覽器視窗來符合其內容，以進行截圖。可以通過在測試內呼叫 disableFitOnFailure 方法來禁用此功能：

1$browser->disableFitOnFailure();1$browser->disableFitOnFailure();

可以使用 move 方法來將瀏覽器視窗移動到畫面上的不同位置：

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

瀏覽器 Macro

若想定義可在各個測試內重複使用的自訂瀏覽器方法，可使用 Browser 類別上的 macro 方法。通常來說，該方法應在某個 Service Provider 的 boot 方法內呼叫：

 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\ServiceProvider;
 6use Laravel\Dusk\Browser;
 7 
 8class DuskServiceProvider extends ServiceProvider
 9{
10    /**
11     * Register Dusk's browser macros.
12     *
13     * @return void
14     */
15    public function boot()
16    {
17        Browser::macro('scrollToElement', function ($element = null) {
18            $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");
19 
20            return $this;
21        });
22    }
23} 1<?php
 2 
 3namespace App\Providers;
 4 
 5use Illuminate\Support\ServiceProvider;
 6use Laravel\Dusk\Browser;
 7 
 8class DuskServiceProvider extends ServiceProvider
 9{
10    /**
11     * Register Dusk's browser macros.
12     *
13     * @return void
14     */
15    public function boot()
16    {
17        Browser::macro('scrollToElement', function ($element = null) {
18            $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");
19 
20            return $this;
21        });
22    }
23}

macro 方法接受一個名稱作為其第一個引數，以及閉包作為其第二個引數。當在 Browser 實體上以方法呼叫該 Macro 時，會執行該 Macro 的閉包：

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

登入認證

一般來說，我們會需要測試需要登入的頁面。可以使用 Dusk 的 loginAs 方法來避免每個測試都需要處理網站的登入畫面。loginAs 方法接受 Authenticatable Model 所關聯的主索引鍵，或是 Authenticatable Model 實體：

1use App\Models\User;
2 
3$this->browse(function ($browser) {
4    $browser->loginAs(User::find(1))
5          ->visit('/home');
6});1use App\Models\User;
2 
3$this->browse(function ($browser) {
4    $browser->loginAs(User::find(1))
5          ->visit('/home');
6});

使用 loginAs 方法後，在該檔案內所有的測試都將使用該使用者 Session。

Cookie

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

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

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

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

可以使用 deleteCookie 方法來刪除給定的 Cookie：

1$browser->deleteCookie('name');1$browser->deleteCookie('name');

執行 JavaScript

可以使用 script 方法來在瀏覽器內執行任意的 JavaScript 陳述式：

1$browser->script('document.documentElement.scrollTop = 0');
2 
3$browser->script([
4    'document.body.scrollTop = 0',
5    'document.documentElement.scrollTop = 0',
6]);
7 
8$output = $browser->script('return window.location.pathname');1$browser->script('document.documentElement.scrollTop = 0');
2 
3$browser->script([
4    'document.body.scrollTop = 0',
5    'document.documentElement.scrollTop = 0',
6]);
7 
8$output = $browser->script('return window.location.pathname');

截圖

可以使用 screenshot 方法來截圖，並將截圖保存為給定的檔案名稱。所有的截圖都會保存在 tests/Browser/screenshots 目錄內：

1$browser->screenshot('filename');1$browser->screenshot('filename');

將主控台輸出保存至磁碟

可以使用 storeConsoleLog 方法來將目前瀏覽器的主控台輸出以給定的檔案名稱寫入到磁碟內。主控台輸出會保存在 tests/Browser/console 目錄內：

1$browser->storeConsoleLog('filename');1$browser->storeConsoleLog('filename');

將頁面原始碼儲存至磁碟

可以使用 storeSource 方法來將目前頁面的原始碼以給定的檔案名稱寫入到磁碟內。頁面原始碼會保存在 tests/Browser/source 目錄內：

1$browser->storeSource('filename');1$browser->storeSource('filename');

與元素互動

Dusk 選擇器

在撰寫 Dusk 測試時，選擇一個好的 CSS 選擇器來與元素互動是最難的一部分。日子一天天過去，當前端有更改時，若有像下列這樣的 CSS 選擇器就有可能讓測試失敗：

1// HTML...
2 
3<button>Login</button>
4 
5// 測試...
6 
7$browser->click('.login-page .container div > button');1// HTML...
2 
3<button>Login</button>
4 
5// 測試...
6 
7$browser->click('.login-page .container div > button');

使用 Dusk 選擇器，就能讓開發人員更專注於撰寫有效的測試，而不是記住 CSS 選擇器。若要定義選擇請，請在 HTML 元素內加上 dusk 屬性。接著，當與 Dusk 瀏覽器互動時，請在該選擇器前方加上 @ 來在測試內操作該元素：

1// HTML...
2 
3<button dusk="login-button">Login</button>
4 
5// 測試...
6 
7$browser->click('@login-button');1// HTML...
2 
3<button dusk="login-button">Login</button>
4 
5// 測試...
6 
7$browser->click('@login-button');

文字、值、與屬性

取得與設定值

Dusk 內提供了數種可與目前頁面上元素的值、顯示文字、與屬性互動的方法。舉例來說，若要在某個符合給定 CSS 或 Dusk 選擇器的元素上取得該元素的「值 (Value)」，可使用 value 方法：

1// 取值...
2$value = $browser->value('selector');
3 
4// 賦值...
5$browser->value('selector', 'value');1// 取值...
2$value = $browser->value('selector');
3 
4// 賦值...
5$browser->value('selector', 'value');

可以使用 inputValue 方法來取得某個給定欄位名稱之 input 元素的「值 (Value)」：

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

取得文字

可使用 text 方法來取得符合給定選擇器之元素的顯示文字：

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

取得屬性

最後，可使用 attribute 方法來取得符合給定選擇器之元素的屬性值：

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

與表單互動

鍵入值

Dusk 提供了多種與表單以及 Input 元素互動的方法。首先，來看看一個在 Input 欄位內鍵入文字的例子：

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

請注意這裡，雖然可將 CSS 選擇器傳入 type 方法，但並不需特別傳入。若未提供 CSS 選擇器，則 Dusk 會搜尋符合給定 name 屬性的 input 或 textarea 欄位。

若要在不將其原本內容清除的情況下將文字附加在最後面，可以使用 append 方法：

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

可以使用 clear 方法來清除某個 Input 的值：

1$browser->clear('email');1$browser->clear('email');

可以使用 typeSlowly 方法來讓 Dusk 輸入得慢一點。預設情況下，Dusk 會在每個按鍵間暫停 100 毫秒。若要自訂按鍵按下間的時間，可將適當的毫秒數作為第三個引數傳給該方法：

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

可以使用 appendSlowly 方法來慢慢地將文字附加到最後：

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

下拉選單

若要在 select 元素上選擇可用的值，可使用 select 方法。與 type 方法類似，select 方法並不要求要提供完整的 CSS 選擇器。將值傳給 select 方法時，應傳入底層的選項值而非顯示的文字：

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

也可以通過省略第二個引數來隨機選擇選項：

1$browser->select('size');1$browser->select('size');

在 select 方法的第二個引數中使用陣列，就可以選擇多個選項：

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

多選框

若要「勾選」多選框，可使用 check 方法。與其他 Input 有關的方法類似，並不需要傳入完整的 CSS 選擇器。若找不到對應的 CSS 選擇器，Dusk 會自動搜尋符合 name 屬性的多選框：

1$browser->check('terms');1$browser->check('terms');

可使用 uncheck 方法來「取消勾選」多選框：

1$browser->uncheck('terms');1$browser->uncheck('terms');

單選框

若要「勾選」radio 單選框，可使用 check 方法。與其他 Input 有關的方法類似，並不需要傳入完整的 CSS 選擇器。若找不到對應的 CSS 選擇器，Dusk 會自動搜尋符合 name 屬性的 radio 單選框：

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

附加檔案

可使用 attach 方法來將檔案附加到 file Input 元素上。與其他 Input 有關的方法類似，並不需要傳入完整的 CSS 選擇器。若找不到對應的 CSS 選擇器，Dusk 會自動搜尋符合 name 屬性的 file Input：

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

要使用 attach 函式，伺服器上必須有安裝 Zip PHP 擴充套件並已啟用。

按下按鈕

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

1$browser->press('Login');1$browser->press('Login');

在送出表單時，許多網站會在按鈕按下的時候禁用表單的送出按鈕，並在表單送出的 HTTP 請求完成後重新啟用該按鈕。若要按下按鈕並等待該按鈕重新啟用，可使用 pressAndWaitFor 方法：

1// 按下按鈕，並等待該按鈕啟用，最多 5 秒...
2$browser->pressAndWaitFor('Save');
3 
4// 按下按鈕，並等待該按鈕啟用，最多 1 秒...
5$browser->pressAndWaitFor('Save', 1);1// 按下按鈕，並等待該按鈕啟用，最多 5 秒...
2$browser->pressAndWaitFor('Save');
3 
4// 按下按鈕，並等待該按鈕啟用，最多 1 秒...
5$browser->pressAndWaitFor('Save', 1);

點擊連結

若要點擊連結，可使用瀏覽器實體上的 clickLink 方法。clickLink 方法會點擊有給定顯示文字的連結：

1$browser->clickLink($linkText);1$browser->clickLink($linkText);

可使用 seeLink 方法來判斷給定的顯示文字是否在頁面上可見：

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

該方法需要與 jQuery 互動。若頁面上沒有 jQuery 可用，則 Dusk 會自動將 jQuery 插入到頁面上以在測試期間使用。

使用鍵盤

比起使用一般的 type 方法，keys 方法提供了可對給定元素進行一系列更複雜輸入的能力。舉例來說，可以讓 Dusk 在輸入數值的時候按著某個輔助按鍵。在這個範例中，於符合給定選擇器的元素內輸入 taylor 文字時，會按著 Shift 鍵。輸入完 taylor 後，swift 會在不按下任何輔助按鍵的情況下輸入：

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

keys 方法的另一個實用用途是給主要 CSS 選擇器傳送一組「鍵盤快捷鍵」：

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

所有的輔助按鍵，如 {command} 都以 {} 字元來進行包裝，且符合 Facebook\WebDriver\WebDriverKeys 中所定義的常數值。可在 GitHub 上找到這些常數值。

使用滑鼠

點擊元素

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

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

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

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

可使用 clickAtPoint 方法來點擊在相對於瀏覽器檢視區域上，符合給定座標點上最上層的元素：

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

可使用 doubleClick 方法來模擬使用滑鼠點兩下：

1$browser->doubleClick();1$browser->doubleClick();

可使用 rightClick 方法來模擬按滑鼠右鍵：

1$browser->rightClick();
2 
3$browser->rightClick('.selector');1$browser->rightClick();
2 
3$browser->rightClick('.selector');

可使用 clickAndHold 方法來模擬按下滑鼠按鈕並保持按下。若接著呼叫 releaseMouse 方法，則會取消這個行為並放開滑鼠按鈕：

1$browser->clickAndHold()
2        ->pause(1000)
3        ->releaseMouse();1$browser->clickAndHold()
2        ->pause(1000)
3        ->releaseMouse();

滑鼠移至上方

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

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

拖放

可使用 drag 方法來將符合給定選擇器元素拖曳至另一個元素上：

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

或者，也可以將某個元素在單一方向上拖曳：

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

最後，可以依照給定偏移值來拖曳元素：

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

JavaScript 對話方塊

Dusk 提供了多種與 JavaScript 對話方塊互動的方法。舉例來說，可以使用 waitForDialog 方法來等待 JavaScript 對話方塊出現。該方法可接收一個可選的引數來判斷要等幾秒讓該對話方塊顯示出來：

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

可使用 assertDialogOpened 方法來判斷某個對話方塊是否已顯示，且包含給定的訊息：

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

若該 JavaScript 對話方塊包含輸入提示，可使用 typeInDialog 方法來在該提示中輸入數值：

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

若要點擊「確定」按鈕來關閉開啟的 JavaScript 對話方塊，可以叫用 acceptDialog 方法：

1$browser->acceptDialog();1$browser->acceptDialog();

若要點擊「取消」按鈕來關閉開啟的 JavaScript 對話方塊，可以叫用 dismissDialog 方法：

1$browser->dismissDialog();1$browser->dismissDialog();

區域性選擇器

有的時候，我們可能會想把多個操作限制到某個特定選擇器裡面。舉例來說，我們在判斷某段文字是否有出現時，可能只想在某個表格內檢查，並在檢查完畢後接著在該表格內點擊某個按鈕。可以使用 with 方法來達成。在提供給 with 方法的閉包內所進行的操作都會被限制在某個選擇器之內：

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

某些時候，我們可能需要在目前的 Scope 外執行 Assertion。可以使用 elsewhere 與 elsewhereWhenAvailable 方法來進行：

 1$browser->with('.table', function ($table) {
 2   // 目前範圍為 `body .table`...
 3 
 4   $browser->elsewhere('.page-title', function ($title) {
 5       // 目前範圍為 `body .page-title`...
 6       $title->assertSee('Hello World');
 7   });
 8 
 9   $browser->elsewhereWhenAvailable('.page-title', function ($title) {
10       // 目前範圍為 `body .page-title`...
11       $title->assertSee('Hello World');
12   });
13}); 1$browser->with('.table', function ($table) {
 2   // 目前範圍為 `body .table`...
 3 
 4   $browser->elsewhere('.page-title', function ($title) {
 5       // 目前範圍為 `body .page-title`...
 6       $title->assertSee('Hello World');
 7   });
 8 
 9   $browser->elsewhereWhenAvailable('.page-title', function ($title) {
10       // 目前範圍為 `body .page-title`...
11       $title->assertSee('Hello World');
12   });
13});

等待元素

在測試使用了大量 JavaScript 的網站時，常常會需要「等待」特定元素或資料出現後才能繼續進行測試。在 Dusk 中可以輕鬆做到。只需要使用幾個方法，就可以等待元素顯示在頁面上，或是等待某個給定的 JavaScript 運算式取值變為 true。

等待

若只是需要將測試暫停幾毫秒，可使用 pause 方法：

1$browser->pause(1000);1$browser->pause(1000);

等待選擇器

waitFor 方法可用來暫停執行測試，並等到符合給定 CSS 或 Dusk 選擇器的元素顯示在頁面上。預設情況下，該方法會最多會暫停測試五秒，超過則會擲回例外。若有需要，可以將自訂的逾時閥值傳入為該方法的第二個引數：

1// 等待選擇器最多 5 秒...
2$browser->waitFor('.selector');
3 
4// 等待選擇器最多 1 秒...
5$browser->waitFor('.selector', 1);1// 等待選擇器最多 5 秒...
2$browser->waitFor('.selector');
3 
4// 等待選擇器最多 1 秒...
5$browser->waitFor('.selector', 1);

也可以等待某個符合給定選擇器的元素出現給定文字：

1// 等待選擇器中包含給定文字最多 5 秒...
2$browser->waitForTextIn('.selector', 'Hello World');
3 
4// 等待選擇器中包含給定文字最多 1 秒...
5$browser->waitForTextIn('.selector', 'Hello World', 1);1// 等待選擇器中包含給定文字最多 5 秒...
2$browser->waitForTextIn('.selector', 'Hello World');
3 
4// 等待選擇器中包含給定文字最多 1 秒...
5$browser->waitForTextIn('.selector', 'Hello World', 1);

也可以等待某個符合給定選擇器的元素消失在頁面上：

1// 等待選擇器不存在，最多 5 秒...
2$browser->waitUntilMissing('.selector');
3 
4// 等待選擇器不存在，最多 1 秒...
5$browser->waitUntilMissing('.selector', 1);1// 等待選擇器不存在，最多 5 秒...
2$browser->waitUntilMissing('.selector');
3 
4// 等待選擇器不存在，最多 1 秒...
5$browser->waitUntilMissing('.selector', 1);

或者，也可以等待給定的選擇器為 Enabled 或 Disabled：

 1// 等待選擇器啟用，最多 5 秒...
 2$browser->waitUntilEnabled('.selector');
 3 
 4// 等待選擇器啟用，最多 1 秒...
 5$browser->waitUntilEnabled('.selector', 1);
 6 
 7// 等待選擇器禁用，最多 5 秒...
 8$browser->waitUntilDisabled('.selector');
 9 
10// 等待選擇器禁用，最多 1 秒...
11$browser->waitUntilDisabled('.selector', 1); 1// 等待選擇器啟用，最多 5 秒...
 2$browser->waitUntilEnabled('.selector');
 3 
 4// 等待選擇器啟用，最多 1 秒...
 5$browser->waitUntilEnabled('.selector', 1);
 6 
 7// 等待選擇器禁用，最多 5 秒...
 8$browser->waitUntilDisabled('.selector');
 9 
10// 等待選擇器禁用，最多 1 秒...
11$browser->waitUntilDisabled('.selector', 1);

可用時進入選擇器的 Scope

有時候我們可能會想等待符合給定選擇器的元素出現在頁面上後再接著與該元素互動。舉例來說，我們可能會想等待某個 Modal 視窗出現，然後在該 Modal 內點擊「OK」按鈕。可以使用 whenAvailable 方法來完成。在給定閉包內進行的所有元素操作都會被限制在原始選擇器的作用範圍內：

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

等待文字

可使用 waitForText 方法來等待給定文字顯示在頁面上：

1// 等待文字，最多 5 秒...
2$browser->waitForText('Hello World');
3 
4// 等待文字，最多 1 秒...
5$browser->waitForText('Hello World', 1);1// 等待文字，最多 5 秒...
2$browser->waitForText('Hello World');
3 
4// 等待文字，最多 1 秒...
5$browser->waitForText('Hello World', 1);

可以使用 waitUntilMissingText 方法來等待某個正在顯示的文字從頁面上移除：

1// 等待文字移除，最多 5 秒...
2$browser->waitUntilMissingText('Hello World');
3 
4// 等待文字移除，最多 1 秒...
5$browser->waitUntilMissingText('Hello World', 1);1// 等待文字移除，最多 5 秒...
2$browser->waitUntilMissingText('Hello World');
3 
4// 等待文字移除，最多 1 秒...
5$browser->waitUntilMissingText('Hello World', 1);

等待連結

可使用 waitForLink 方法來等待給定連結文字顯示在頁面上：

1// 等待連結，最多 5 秒...
2$browser->waitForLink('Create');
3 
4// 等待連結，最多 1 秒...
5$browser->waitForLink('Create', 1);1// 等待連結，最多 5 秒...
2$browser->waitForLink('Create');
3 
4// 等待連結，最多 1 秒...
5$browser->waitForLink('Create', 1);

等待網頁位置

在進行如 $browser->assertPathIs('/home') 這種路徑 Assertion 時，如果 window.location.pathname 是非同步更新的，則該 Assertion 可能會失敗。可以使用 waitForLocation 方法來等待路徑為給定的值：

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

也可以使用 waitForLocation 方法來等待目前視窗的路徑符合完整的 URL：

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

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

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

等待頁面重新整理

若有需要在執行特定動作前等待頁面重新整理，請使用 waitForReload 方法：

1use Laravel\Dusk\Browser;
2 
3$browser->waitForReload(function (Browser $browser) {
4    $browser->press('Submit');
5})
6->assertSee('Success!');1use Laravel\Dusk\Browser;
2 
3$browser->waitForReload(function (Browser $browser) {
4    $browser->press('Submit');
5})
6->assertSee('Success!');

由於我們通常會在點擊按鈕後等待頁面重新整理，因此可以使用更方便的 clickAndWaitForReload 方法：

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

等待 JavaScript 運算式

有時候，我們可能會想暫停測試並等待某個給定的 JavaScript 運算式取值為 true。可使用 waitUntil 方法來輕鬆達成。將運算式傳給該方法時，不需要包含 return 關鍵字或結尾的分號：

1// 等待運算式為 True，最多 5 秒...
2$browser->waitUntil('App.data.servers.length > 0');
3 
4// 等待運算式為 True，最多 1 秒...
5$browser->waitUntil('App.data.servers.length > 0', 1);1// 等待運算式為 True，最多 5 秒...
2$browser->waitUntil('App.data.servers.length > 0');
3 
4// 等待運算式為 True，最多 1 秒...
5$browser->waitUntil('App.data.servers.length > 0', 1);

等待 Vue 運算式

可使用 waitUntilVue 與 waitUntilVueIsNot 方法來等待給定的 Vue 元件屬性具有給定的值：

1// 等待直到 Vue 元件的屬性包含給定值...
2$browser->waitUntilVue('user.name', 'Taylor', '@user');
3 
4// 等待直到 Vue 元件的屬性不包含給定值...
5$browser->waitUntilVueIsNot('user.name', null, '@user');1// 等待直到 Vue 元件的屬性包含給定值...
2$browser->waitUntilVue('user.name', 'Taylor', '@user');
3 
4// 等待直到 Vue 元件的屬性不包含給定值...
5$browser->waitUntilVueIsNot('user.name', null, '@user');

包含回呼的等待

在 Dusk 中，許多的「wait」方法都仰賴於底層的 waitUsing 方法。可以直接使用該方法來等待給定的閉包回傳 true。waitUsing 方法接受等待最大秒數、閉包取值的時間間隔、閉包、以及一個可選的錯誤訊息：

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

將元素滾動進也沒

有時候，我們可能沒辦法點擊某個元素，因為該元素在瀏覽器可視區域外。使用 scrollIntoView 方法可以滾動瀏覽器視窗，直到給定選擇器元素出現在顯示區內：

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

可用的 Assertion

Dusk 提供了多種可對網站進行的 Assertion。下面列出了所有可用的 Assertion：

assertTitle assertTitleContains assertUrlIs assertSchemeIs assertSchemeIsNot assertHostIs assertHostIsNot assertPortIs assertPortIsNot assertPathBeginsWith assertPathIs assertPathIsNot assertRouteIs assertQueryStringHas assertQueryStringMissing assertFragmentIs assertFragmentBeginsWith assertFragmentIsNot assertHasCookie assertHasPlainCookie assertCookieMissing assertPlainCookieMissing assertCookieValue assertPlainCookieValue assertSee assertDontSee assertSeeIn assertDontSeeIn assertSeeAnythingIn assertSeeNothingIn assertScript assertSourceHas assertSourceMissing assertSeeLink assertDontSeeLink assertInputValue assertInputValueIsNot assertChecked assertNotChecked assertRadioSelected assertRadioNotSelected assertSelected assertNotSelected assertSelectHasOptions assertSelectMissingOptions assertSelectHasOption assertSelectMissingOption assertValue assertValueIsNot assertAttribute assertAttributeContains assertAriaAttribute assertDataAttribute assertVisible assertPresent assertNotPresent assertMissing assertInputPresent assertInputMissing assertDialogOpened assertEnabled assertDisabled assertButtonEnabled assertButtonDisabled assertFocused assertNotFocused assertAuthenticated assertGuest assertAuthenticatedAs assertVue assertVueIsNot assertVueContains assertVueDoesNotContain

assertTitle

判斷頁面標題符合給定文字：

1$browser->assertTitle($title);1$browser->assertTitle($title);

assertTitleContains

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

1$browser->assertTitleContains($title);1$browser->assertTitleContains($title);

assertUrlIs

判斷目前 URL (不含查詢字串 Query String) 符合給定字串：

1$browser->assertUrlIs($url);1$browser->assertUrlIs($url);

assertSchemeIs

判斷目前 URL 的協定 (Scheme) 符合給定協定：

1$browser->assertSchemeIs($scheme);1$browser->assertSchemeIs($scheme);

assertSchemeIsNot

判斷目前的 URL 協定 (Scheme) 不符合給定協定：

1$browser->assertSchemeIsNot($scheme);1$browser->assertSchemeIsNot($scheme);

assertHostIs

判斷目前 URL 的主機名稱 (Host) 符合給定主機名稱：

1$browser->assertHostIs($host);1$browser->assertHostIs($host);

assertHostIsNot

判斷目前 URL 的主機名稱 (Host) 不符合給定主機名稱：

1$browser->assertHostIsNot($host);1$browser->assertHostIsNot($host);

assertPortIs

判斷目前 URL 的連接埠 (Port) 符合給定連接埠：

1$browser->assertPortIs($port);1$browser->assertPortIs($port);

assertPortIsNot

判斷目前 URL 的連接埠 (Port) 不符合給定連接埠：

1$browser->assertPortIsNot($port);1$browser->assertPortIsNot($port);

assertPathBeginsWith

判斷目前 URL 的路徑 (Path) 以給定路徑開始：

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

assertPathIs

判斷目前路徑 (Path) 符合給定路徑：

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

assertPathIsNot

判斷目前路徑不符合給定路徑：

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

assertRouteIs

判斷目前 URL 符合給定的命名路由 URL：

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

assertQueryStringHas

判斷查詢字串 (Query String) 有包含給定參數：

1$browser->assertQueryStringHas($name);1$browser->assertQueryStringHas($name);

判斷查詢字串有包含給定參數，並符合給定的值：

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

assertQueryStringMissing

判斷查詢字串 (Query String) 不包含給定的參數：

1$browser->assertQueryStringMissing($name);1$browser->assertQueryStringMissing($name);

assertFragmentIs

判斷 URL 目前的雜湊片段 (Hash Fragment) 符合給定的片段：

1$browser->assertFragmentIs('anchor');1$browser->assertFragmentIs('anchor');

assertFragmentBeginsWith

判斷 URL 目前的雜湊片段 (Hash Fragment) 以給定的片段開始：

1$browser->assertFragmentBeginsWith('anchor');1$browser->assertFragmentBeginsWith('anchor');

assertFragmentIsNot

判斷 URL 目前的雜湊片段 (Hash Fragment) 不符合給定的片段：

1$browser->assertFragmentIsNot('anchor');1$browser->assertFragmentIsNot('anchor');

判斷 Cookie 中含有給定的加密 Cookie：

1$browser->assertHasCookie($name);1$browser->assertHasCookie($name);

判斷 Cookie 中含有給定的未加密 Cookie：

1$browser->assertHasPlainCookie($name);1$browser->assertHasPlainCookie($name);

判斷 Cookie 中不包含給定的加密 Cookie：

1$browser->assertCookieMissing($name);1$browser->assertCookieMissing($name);

判斷 Cookie 中不包含給定的未加密 Cookie：

1$browser->assertPlainCookieMissing($name);1$browser->assertPlainCookieMissing($name);

判斷加密 Cookie 為給定的值：

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

判斷未加密 Cookie 為給定的值：

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

assertSee

判斷給定文字有出現在頁面上：

1$browser->assertSee($text);1$browser->assertSee($text);

assertDontSee

判斷給定文字未出現在頁面上：

1$browser->assertDontSee($text);1$browser->assertDontSee($text);

assertSeeIn

判斷給定文字出現在選擇器中：

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

assertDontSeeIn

判斷給定文字未出現在選擇器中：

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

assertSeeAnythingIn

判斷選擇器中有包含任何文字：

1$browser->assertSeeAnythingIn($selector);1$browser->assertSeeAnythingIn($selector);

assertSeeNothingIn

判斷選擇器中未包含任何文字：

1$browser->assertSeeNothingIn($selector);1$browser->assertSeeNothingIn($selector);

assertScript

判斷給定的 JavaScript 運算式取值為給定的值：

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

assertSourceHas

判斷給定的原始碼有出現在頁面上：

1$browser->assertSourceHas($code);1$browser->assertSourceHas($code);

assertSourceMissing

判斷給定的原始碼未出現在頁面上：

1$browser->assertSourceMissing($code);1$browser->assertSourceMissing($code);

assertSeeLink

判斷給定連結有出現在頁面上：

1$browser->assertSeeLink($linkText);1$browser->assertSeeLink($linkText);

assertDontSeeLink

判斷給定連結未出現在頁面上：

1$browser->assertDontSeeLink($linkText);1$browser->assertDontSeeLink($linkText);

assertInputValue

判斷給定的輸入欄位為給定值：

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

assertInputValueIsNot

判斷給定的輸入欄位不是給定值：

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

assertChecked

判斷給定多選況已勾選：

1$browser->assertChecked($field);1$browser->assertChecked($field);

assertNotChecked

判斷給定多選況未勾選：

1$browser->assertNotChecked($field);1$browser->assertNotChecked($field);

assertRadioSelected

判斷給定單選框欄位已選擇：

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

assertRadioNotSelected

判斷給定單選框欄位未選擇：

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

assertSelected

判斷給定下拉選單已選擇給定值：

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

assertNotSelected

判斷給定下拉選單未選擇給定值：

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

assertSelectHasOptions

判斷給定陣列中的值可被選取：

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

assertSelectMissingOptions

判斷給定陣列中的值不可被選取：

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

assertSelectHasOption

判斷給定值在給定欄位中可被選取：

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

assertSelectMissingOption

判斷給定值不可被選取：

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

assertValue

判斷符合給定選擇器的元素符合給定值：

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

assertValueIsNot

判斷符合給定選擇器的元素不符合給定值：

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

assertAttribute

判斷符合給定選擇器的元素中指定的屬性為給定值：

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

assertAttributeContains

判斷符合給定選擇器的元素中指定的屬性包含給定值：

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

assertAriaAttribute

判斷符合給定選擇器的元素中指定的 Aria 屬性為給定值：

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

舉例來說，若有 <button aria-label="Add"> 標記，則可像這樣判斷 aria-label 屬性：

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

assertDataAttribute

判斷符合給定選擇器的元素中指定的 Data 屬性為給定值：

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

舉例來說，若有 <tr id="row-1" data-content="attendees"></tr> 標記，則可像這樣判斷 data-label 屬性：

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

assertVisible

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

1$browser->assertVisible($selector);1$browser->assertVisible($selector);

assertPresent

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

1$browser->assertPresent($selector);1$browser->assertPresent($selector);

assertNotPresent

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

1$browser->assertNotPresent($selector);1$browser->assertNotPresent($selector);

assertMissing

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

1$browser->assertMissing($selector);1$browser->assertMissing($selector);

assertInputPresent

判斷給定名稱的輸入欄位存在：

1$browser->assertInputPresent($name);1$browser->assertInputPresent($name);

assertInputMissing

判斷給定名稱的輸入欄位不存在：

1$browser->assertInputMissing($name);1$browser->assertInputMissing($name);

assertDialogOpened

判斷有給定訊息的 JavaScript 對話方塊開啟：

1$browser->assertDialogOpened($message);1$browser->assertDialogOpened($message);

assertEnabled

判斷給定欄位啟用：

1$browser->assertEnabled($field);1$browser->assertEnabled($field);

assertDisabled

判斷給定欄位禁用：

1$browser->assertDisabled($field);1$browser->assertDisabled($field);

assertButtonEnabled

判斷給定按鈕啟用：

1$browser->assertButtonEnabled($button);1$browser->assertButtonEnabled($button);

assertButtonDisabled

判斷給定按鈕禁用：

1$browser->assertButtonDisabled($button);1$browser->assertButtonDisabled($button);

assertFocused

判斷給定欄位已聚焦：

1$browser->assertFocused($field);1$browser->assertFocused($field);

assertNotFocused

判斷給定欄位未聚焦：

1$browser->assertNotFocused($field);1$browser->assertNotFocused($field);

assertAuthenticated

判斷使用者已登入：

1$browser->assertAuthenticated();1$browser->assertAuthenticated();

assertGuest

判斷使用者未登入：

1$browser->assertGuest();1$browser->assertGuest();

assertAuthenticatedAs

判斷使用者已登入為給定使用者：

1$browser->assertAuthenticatedAs($user);1$browser->assertAuthenticatedAs($user);

assertVue

在 Dusk 中，甚至可以對 Vue 元件資料的狀態進行 Assertion。舉例來說，假設網站中包含下列 Vue 元件：

 1// HTML...
 2 
 3<profile dusk="profile-component"></profile>
 4 
 5// 元件定義...
 6 
 7Vue.component('profile', {
 8    template: '<div>{{ user.name }}</div>',
 9 
10    data: function () {
11        return {
12            user: {
13                name: 'Taylor'
14            }
15        };
16    }
17}); 1// HTML...
 2 
 3<profile dusk="profile-component"></profile>
 4 
 5// 元件定義...
 6 
 7Vue.component('profile', {
 8    template: '<div>{{ user.name }}</div>',
 9 
10    data: function () {
11        return {
12            user: {
13                name: 'Taylor'
14            }
15        };
16    }
17});

則可像這樣判斷 Vue 元件的狀態：

 1/**
 2 * A basic Vue test example.
 3 *
 4 * @return void
 5 */
 6public function testVue()
 7{
 8    $this->browse(function (Browser $browser) {
 9        $browser->visit('/')
10                ->assertVue('user.name', 'Taylor', '@profile-component');
11    });
12} 1/**
 2 * A basic Vue test example.
 3 *
 4 * @return void
 5 */
 6public function testVue()
 7{
 8    $this->browse(function (Browser $browser) {
 9        $browser->visit('/')
10                ->assertVue('user.name', 'Taylor', '@profile-component');
11    });
12}

assertVueIsNot

判斷給定的 Vue 元件資料屬性不符合給定值：

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

assertVueContains

判斷給定的 Vue 元件資料屬性為陣列，並包含給定值：

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

assertVueDoesNotContain

判斷給定的 Vue 元件資料屬性為陣列，並且不包含給定值：

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

Page

有時候，測試可能會需要按照順序執行多個複雜的動作。這樣一來可能會使測試難以閱讀與理解。通過 Dusk Page，便可定義描述性的動作，並以單一方法來在給定頁面上執行。使用 Page 還可為網站或單一頁面上常用的選擇器定義捷徑。

產生 Page

若要產生 Page 物件，請執行 dusk:page Artisan 指令。

1php artisan dusk:page Login1php artisan dusk:page Login

設定 Page

預設情況下，Page 有三個方法：url、assert、與 elements。我們現在先來討論 url 與 assert 方法。稍後會來詳細討論有關 elements 方法。

`url` 方法

url 方法應回傳代表該 Page 的 URL 之路徑。在瀏覽器中前往該頁面時，Dusk 會使用該 URL：

1/**
2 * Get the URL for the page.
3 *
4 * @return string
5 */
6public function url()
7{
8    return '/login';
9}1/**
2 * Get the URL for the page.
3 *
4 * @return string
5 */
6public function url()
7{
8    return '/login';
9}

`assert` 方法

assert 方法可進行任意的 Assertion 判斷，來認證瀏覽器是否確實在該頁面上。該方法中不一定要有內容。不過，若有需要，可以自行進行 Assertion。這些 Assertion 會在前往該頁面後被自動執行：

1/**
2 * Assert that the browser is on the page.
3 *
4 * @return void
5 */
6public function assert(Browser $browser)
7{
8    $browser->assertPathIs($this->url());
9}1/**
2 * Assert that the browser is on the page.
3 *
4 * @return void
5 */
6public function assert(Browser $browser)
7{
8    $browser->assertPathIs($this->url());
9}

前往 Page

Page 建立好後，就可以使用 visit 方法來前往該 Page：

1use Tests\Browser\Pages\Login;
2 
3$browser->visit(new Login);1use Tests\Browser\Pages\Login;
2 
3$browser->visit(new Login);

有時候，我們可能已經在某個給定頁面上，並且只需要將該頁面的選擇器與方法「載入」進目前的測試內容即可。常見的例子如通過點擊按鈕後跳轉至給定的頁面，而不是顯式前往該頁面。在此情況下，可使用 on 方法來載入頁面：

1use Tests\Browser\Pages\CreatePlaylist;
2 
3$browser->visit('/dashboard')
4        ->clickLink('Create Playlist')
5        ->on(new CreatePlaylist)
6        ->assertSee('@create');1use Tests\Browser\Pages\CreatePlaylist;
2 
3$browser->visit('/dashboard')
4        ->clickLink('Create Playlist')
5        ->on(new CreatePlaylist)
6        ->assertSee('@create');

選擇器簡寫

Page 類別中的 elements 方法可讓你為頁面上的任意 CSS 選擇器定義快速、簡單好記的簡寫。舉例來說，來為網站登入頁的「email」輸入欄位定義捷徑：

 1/**
 2 * Get the element shortcuts for the page.
 3 *
 4 * @return array
 5 */
 6public function elements()
 7{
 8    return [
 9        '@email' => 'input[name=email]',
10    ];
11} 1/**
 2 * Get the element shortcuts for the page.
 3 *
 4 * @return array
 5 */
 6public function elements()
 7{
 8    return [
 9        '@email' => 'input[name=email]',
10    ];
11}

定義好捷徑後，就可以在其他通常需要使用完整 CSS 選擇器的地方使用該選擇器簡寫：

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

全域選擇器簡寫

安裝好 Dusk 後，tests/Browser/Pages 目錄下會包含一個基礎的 Page 類別。該類別包含了一個 siteElements 方法，可用來定義在網站中所有頁面都可用的全域選擇器簡寫：

 1/**
 2 * Get the global element shortcuts for the site.
 3 *
 4 * @return array
 5 */
 6public static function siteElements()
 7{
 8    return [
 9        '@element' => '#selector',
10    ];
11} 1/**
 2 * Get the global element shortcuts for the site.
 3 *
 4 * @return array
 5 */
 6public static function siteElements()
 7{
 8    return [
 9        '@element' => '#selector',
10    ];
11}

Page 方法

除了 Page 中預設定義的方法外，也可以定義額外的方法來在測試中使用。舉例來說，假設我們正在製作一個音樂管理軟體。在該軟體中，建立播放清單可能會是個常見的動作。比起在每個測試中重複撰寫建立播放清單的邏輯，我們可以在 Page 類別內定義 createPlaylist 方法：

 1<?php
 2 
 3namespace Tests\Browser\Pages;
 4 
 5use Laravel\Dusk\Browser;
 6 
 7class Dashboard extends Page
 8{
 9    // Other page methods...
10 
11    /**
12     * Create a new playlist.
13     *
14     * @param  \Laravel\Dusk\Browser  $browser
15     * @param  string  $name
16     * @return void
17     */
18    public function createPlaylist(Browser $browser, $name)
19    {
20        $browser->type('name', $name)
21                ->check('share')
22                ->press('Create Playlist');
23    }
24} 1<?php
 2 
 3namespace Tests\Browser\Pages;
 4 
 5use Laravel\Dusk\Browser;
 6 
 7class Dashboard extends Page
 8{
 9    // Other page methods...
10 
11    /**
12     * Create a new playlist.
13     *
14     * @param  \Laravel\Dusk\Browser  $browser
15     * @param  string  $name
16     * @return void
17     */
18    public function createPlaylist(Browser $browser, $name)
19    {
20        $browser->type('name', $name)
21                ->check('share')
22                ->press('Create Playlist');
23    }
24}

定義好該方法後，就可以在任何使用該 Page 的測試中使用該方法。Browser 實體會自動作為第一個引數傳入給自訂 Page 方法內：

1use Tests\Browser\Pages\Dashboard;
2 
3$browser->visit(new Dashboard)
4        ->createPlaylist('My Playlist')
5        ->assertSee('My Playlist');1use Tests\Browser\Pages\Dashboard;
2 
3$browser->visit(new Dashboard)
4        ->createPlaylist('My Playlist')
5        ->assertSee('My Playlist');

元件

Component (元件) 與 Dusk 的「Page 物件」類似，不同的地方在於元件是用於一小部分的 UI，且在整個網站中都可重複使用。如：導航列或通知視窗。因此，元件並不限定於特定的 URL。

產生 Component

若要產生 Component，請執行 dusk:component Artisan 指令。新建立的 Component 會放置於 tests/Browser/Components 目錄中：

1php artisan dusk:component DatePicker1php artisan dusk:component DatePicker

像上面這樣，「date picker」是一個範例元件，該元件可能會在網站的各種頁面上出現。若要在測試套件中的數十個測試內手動轉寫瀏覽器自動化邏輯會很麻煩。因此，我們可以改用 Dusk Component 來代表 Date Picker，進而將此一邏輯封裝在該元件內：

 1<?php
 2 
 3namespace Tests\Browser\Components;
 4 
 5use Laravel\Dusk\Browser;
 6use Laravel\Dusk\Component as BaseComponent;
 7 
 8class DatePicker extends BaseComponent
 9{
10    /**
11     * Get the root selector for the component.
12     *
13     * @return string
14     */
15    public function selector()
16    {
17        return '.date-picker';
18    }
19 
20    /**
21     * Assert that the browser page contains the component.
22     *
23     * @param  Browser  $browser
24     * @return void
25     */
26    public function assert(Browser $browser)
27    {
28        $browser->assertVisible($this->selector());
29    }
30 
31    /**
32     * Get the element shortcuts for the component.
33     *
34     * @return array
35     */
36    public function elements()
37    {
38        return [
39            '@date-field' => 'input.datepicker-input',
40            '@year-list' => 'div > div.datepicker-years',
41            '@month-list' => 'div > div.datepicker-months',
42            '@day-list' => 'div > div.datepicker-days',
43        ];
44    }
45 
46    /**
47     * Select the given date.
48     *
49     * @param  \Laravel\Dusk\Browser  $browser
50     * @param  int  $year
51     * @param  int  $month
52     * @param  int  $day
53     * @return void
54     */
55    public function selectDate(Browser $browser, $year, $month, $day)
56    {
57        $browser->click('@date-field')
58                ->within('@year-list', function ($browser) use ($year) {
59                    $browser->click($year);
60                })
61                ->within('@month-list', function ($browser) use ($month) {
62                    $browser->click($month);
63                })
64                ->within('@day-list', function ($browser) use ($day) {
65                    $browser->click($day);
66                });
67    }
68} 1<?php
 2 
 3namespace Tests\Browser\Components;
 4 
 5use Laravel\Dusk\Browser;
 6use Laravel\Dusk\Component as BaseComponent;
 7 
 8class DatePicker extends BaseComponent
 9{
10    /**
11     * Get the root selector for the component.
12     *
13     * @return string
14     */
15    public function selector()
16    {
17        return '.date-picker';
18    }
19 
20    /**
21     * Assert that the browser page contains the component.
22     *
23     * @param  Browser  $browser
24     * @return void
25     */
26    public function assert(Browser $browser)
27    {
28        $browser->assertVisible($this->selector());
29    }
30 
31    /**
32     * Get the element shortcuts for the component.
33     *
34     * @return array
35     */
36    public function elements()
37    {
38        return [
39            '@date-field' => 'input.datepicker-input',
40            '@year-list' => 'div > div.datepicker-years',
41            '@month-list' => 'div > div.datepicker-months',
42            '@day-list' => 'div > div.datepicker-days',
43        ];
44    }
45 
46    /**
47     * Select the given date.
48     *
49     * @param  \Laravel\Dusk\Browser  $browser
50     * @param  int  $year
51     * @param  int  $month
52     * @param  int  $day
53     * @return void
54     */
55    public function selectDate(Browser $browser, $year, $month, $day)
56    {
57        $browser->click('@date-field')
58                ->within('@year-list', function ($browser) use ($year) {
59                    $browser->click($year);
60                })
61                ->within('@month-list', function ($browser) use ($month) {
62                    $browser->click($month);
63                })
64                ->within('@day-list', function ($browser) use ($day) {
65                    $browser->click($day);
66                });
67    }
68}

使用 Component

定義好 Component 後，便可輕鬆地在任何測試內於 Date Picker 中選擇日期。而且，若選擇日期所需要的邏輯更改了，我們只需要更新 Component 即可：

 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use Illuminate\Foundation\Testing\DatabaseMigrations;
 6use Laravel\Dusk\Browser;
 7use Tests\Browser\Components\DatePicker;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    /**
13     * A basic component test example.
14     *
15     * @return void
16     */
17    public function testBasicExample()
18    {
19        $this->browse(function (Browser $browser) {
20            $browser->visit('/')
21                    ->within(new DatePicker, function ($browser) {
22                        $browser->selectDate(2019, 1, 30);
23                    })
24                    ->assertSee('January');
25        });
26    }
27} 1<?php
 2 
 3namespace Tests\Browser;
 4 
 5use Illuminate\Foundation\Testing\DatabaseMigrations;
 6use Laravel\Dusk\Browser;
 7use Tests\Browser\Components\DatePicker;
 8use Tests\DuskTestCase;
 9 
10class ExampleTest extends DuskTestCase
11{
12    /**
13     * A basic component test example.
14     *
15     * @return void
16     */
17    public function testBasicExample()
18    {
19        $this->browse(function (Browser $browser) {
20            $browser->visit('/')
21                    ->within(new DatePicker, function ($browser) {
22                        $browser->selectDate(2019, 1, 30);
23                    })
24                    ->assertSee('January');
25        });
26    }
27}

持續整合 (CI, Continuous Integration)

大多數的 Dusk CI 設定都假設你的 Laravel 應用程式放在連接埠 8000 的 PHP 內建開發伺服器上。因此，在繼續前，請先確保 CI 環境上有將 APP_URL 環境變數設為 http://127.0.0.1:8000。

Heroku CI

若要在 Heroku CI 上執行 Dusk 測試，請將下列 Google Chrome Buildpack 與指令嗎加到 Heroku 的 app.json 檔中：

 1{
 2  "environments": {
 3    "test": {
 4      "buildpacks": [
 5        { "url": "heroku/php" },
 6        { "url": "https://github.com/heroku/heroku-buildpack-google-chrome" }
 7      ],
 8      "scripts": {
 9        "test-setup": "cp .env.testing .env",
10        "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
11      }
12    }
13  }
14} 1{
 2  "environments": {
 3    "test": {
 4      "buildpacks": [
 5        { "url": "heroku/php" },
 6        { "url": "https://github.com/heroku/heroku-buildpack-google-chrome" }
 7      ],
 8      "scripts": {
 9        "test-setup": "cp .env.testing .env",
10        "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
11      }
12    }
13  }
14}

Travis CI

若要在 Travis CI 上執行 Dusk 測試，請使用下列 .travis.yml 設定檔。由於 Travis CI 並非圖形化環境，因此若要啟動 Chrome 瀏覽器，我們需要做一些額外的步驟。此外，我們會使用 php artisan serve 來啟動 PHP 的內建網頁伺服器：

 1language: php
 2 
 3php:
 4  - 7.3
 5 
 6addons:
 7  chrome: stable
 8 
 9install:
10  - cp .env.testing .env
11  - travis_retry composer install --no-interaction --prefer-dist
12  - php artisan key:generate
13  - php artisan dusk:chrome-driver
14 
15before_script:
16  - google-chrome-stable --headless --disable-gpu --remote-debugging-port=9222 http://localhost &
17  - php artisan serve --no-reload &
18 
19script:
20  - php artisan dusk 1language: php
 2 
 3php:
 4  - 7.3
 5 
 6addons:
 7  chrome: stable
 8 
 9install:
10  - cp .env.testing .env
11  - travis_retry composer install --no-interaction --prefer-dist
12  - php artisan key:generate
13  - php artisan dusk:chrome-driver
14 
15before_script:
16  - google-chrome-stable --headless --disable-gpu --remote-debugging-port=9222 http://localhost &
17  - php artisan serve --no-reload &
18 
19script:
20  - php artisan dusk

GitHub Actions

若要使用 Github Actions 來執行 Dusk 測試，可參考下列設定檔。與 TravisCI 一樣，我們會使用 php artisan serve 指令來啟動 PHP 的內建網頁伺服器：

 1name: CI
 2on: [push]
 3jobs:
 4 
 5  dusk-php:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v2
 9      - name: Prepare The Environment
10        run: cp .env.example .env
11      - name: Create Database
12        run: |
13          sudo systemctl start mysql
14          mysql --user="root" --password="root" -e "CREATE DATABASE 'my-database' character set UTF8mb4 collate utf8mb4_bin;"
15      - name: Install Composer Dependencies
16        run: composer install --no-progress --prefer-dist --optimize-autoloader
17      - name: Generate Application Key
18        run: php artisan key:generate
19      - name: Upgrade Chrome Driver
20        run: php artisan dusk:chrome-driver `/opt/google/chrome/chrome --version | cut -d " " -f3 | cut -d "." -f1`
21      - name: Start Chrome Driver
22        run: ./vendor/laravel/dusk/bin/chromedriver-linux &
23      - name: Run Laravel Server
24        run: php artisan serve --no-reload &
25      - name: Run Dusk Tests
26        env:
27          APP_URL: "http://127.0.0.1:8000"
28        run: php artisan dusk
29      - name: Upload Screenshots
30        if: failure()
31        uses: actions/upload-artifact@v2
32        with:
33          name: screenshots
34          path: tests/Browser/screenshots
35      - name: Upload Console Logs
36        if: failure()
37        uses: actions/upload-artifact@v2
38        with:
39          name: console
40          path: tests/Browser/console 1name: CI
 2on: [push]
 3jobs:
 4 
 5  dusk-php:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v2
 9      - name: Prepare The Environment
10        run: cp .env.example .env
11      - name: Create Database
12        run: |
13          sudo systemctl start mysql
14          mysql --user="root" --password="root" -e "CREATE DATABASE 'my-database' character set UTF8mb4 collate utf8mb4_bin;"
15      - name: Install Composer Dependencies
16        run: composer install --no-progress --prefer-dist --optimize-autoloader
17      - name: Generate Application Key
18        run: php artisan key:generate
19      - name: Upgrade Chrome Driver
20        run: php artisan dusk:chrome-driver `/opt/google/chrome/chrome --version | cut -d " " -f3 | cut -d "." -f1`
21      - name: Start Chrome Driver
22        run: ./vendor/laravel/dusk/bin/chromedriver-linux &
23      - name: Run Laravel Server
24        run: php artisan serve --no-reload &
25      - name: Run Dusk Tests
26        env:
27          APP_URL: "http://127.0.0.1:8000"
28        run: php artisan dusk
29      - name: Upload Screenshots
30        if: failure()
31        uses: actions/upload-artifact@v2
32        with:
33          name: screenshots
34          path: tests/Browser/screenshots
35      - name: Upload Console Logs
36        if: failure()
37        uses: actions/upload-artifact@v2
38        with:
39          name: console
40          path: tests/Browser/console