Laravel Dusk

简介

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 测试，并安装适用于您操作系统的 ChromeDriver 二进制文件：

php artisan dusk:install

接下来，在应用程序的 .env 文件中设置 APP_URL 环境变量。此值应与您在浏览器中访问应用程序时使用的 URL 相匹配。

如果您使用 Laravel Sail 来管理本地开发环境，请查阅 Sail 文档，了解如何【配置和运行 Dusk 测试】。

管理 ChromeDriver 安装

如果您想安装与 Laravel Dusk 通过 dusk:install 命令安装的版本不同的 ChromeDriver 版本，可以使用 dusk:chrome-driver 命令：

# 为您的操作系统安装最新版本的 ChromeDriver...
php artisan dusk:chrome-driver

# 为您的操作系统安装指定版本的 ChromeDriver...
php artisan dusk:chrome-driver 86

# 为所有支持的操作系统安装指定版本的 ChromeDriver...
php artisan dusk:chrome-driver --all

# 安装与您操作系统上检测到的 Chrome / Chromium 版本匹配的 ChromeDriver...
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：

/**
 * 准备 Dusk 测试执行。
 *
 * @beforeClass
 */
public static function prepare(): void
{
    // static::startChromeDriver();
}

接下来，您可以修改 driver 方法，连接到您选择的 URL 和端口。此外，您可以修改应该传递给 WebDriver 的“期望能力”：

use Facebook\WebDriver\Remote\RemoteWebDriver;

/**
 * 创建 RemoteWebDriver 实例。
 */
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。

使用数据库迁移（Database Migrations）

DatabaseMigrations trait 会在每个测试之前运行数据库迁移。然而，对于每个测试都丢弃并重新创建数据库表，通常比清空表的速度要慢：

  • Pest

  • PHPUnit

<?php

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

uses(DatabaseMigrations::class);

//
<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    //
}

执行 Dusk 测试时，不能使用 SQLite 内存数据库。由于浏览器在其自己的进程中执行，它将无法访问其它进程的内存数据库。

使用数据库清空（Database Truncation）

DatabaseTruncation trait 会在第一次测试时迁移数据库，以确保数据库表已经正确创建。然而，在随后的测试中，数据库的表将只是被清空，这比重新运行所有数据库迁移更快：

  • Pest

  • PHPUnit

<?php

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

uses(DatabaseTruncation::class);

//
<?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;

    //
}

默认情况下，DatabaseTruncation trait 会清空所有表，除了迁移表。如果您想自定义需要清空的表，可以在测试类中定义 $tablesToTruncate 属性：

如果您使用 Pest，您应该在基础的 DuskTestCase 类或任何您的测试文件继承的类中定义属性或方法。

 
/**
 * 指定需要清空的表。
 *
 * @var array
 */
protected $tablesToTruncate = ['users'];

或者，您可以在测试类中定义一个 $exceptTables 属性，指定哪些表不应被清空：

/**
 * 指定哪些表不应被清空。
 *
 * @var array
 */
protected $exceptTables = ['users'];

要指定应该清空其表的数据库连接，您可以在测试类中定义 $connectionsToTruncate 属性：

/**
 * 指定哪些连接的表应该被清空。
 *
 * @var array
 */
protected $connectionsToTruncate = ['mysql'];

如果您希望在执行数据库清空操作之前或之后执行某些代码，可以在测试类中定义 beforeTruncatingDatabase 或 afterTruncatingDatabase 方法：

/**
 * 在数据库开始清空之前执行任何工作。
 */
protected function beforeTruncatingDatabase(): void
{
    //
}

/**
 * 在数据库清空完成后执行任何工作。
 */
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 文件中的以下行：

/**
 * 准备 Dusk 测试执行。
 *
 * @beforeClass
 */
public static function prepare(): void
{
    // static::startChromeDriver();
}

此外，如果您在非 9515 端口上启动 ChromeDriver，您应该修改同一类中的 driver 方法，以反映正确的端口：

use Facebook\WebDriver\Remote\RemoteWebDriver;

/**
 * 创建 RemoteWebDriver 实例。
 */
protected function driver(): RemoteWebDriver
{
    return RemoteWebDriver::create(
        'http://localhost:9515', DesiredCapabilities::chrome()
    );
}

环境处理

要强制 Dusk 在运行测试时使用自己的环境文件，请在项目根目录下创建一个 .env.dusk.{environment} 文件。例如，如果您将在本地环境中启动 dusk 命令，则应创建一个 .env.dusk.local 文件。

在运行测试时，Dusk 会备份您的 .env 文件，并将您的 Dusk 环境文件重命名为 .env。测试完成后，Dusk 会恢复您的 .env 文件。

浏览器基础

创建浏览器

让我们首先编写一个测试，验证我们可以登录到应用程序。在生成测试后，我们可以修改它以导航到登录页面，输入凭据，并点击 “登录” 按钮。要创建一个浏览器实例，您可以在 Dusk 测试中调用 browse 方法：

  • Pest

  • PHPUnit

<?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' => 'taylor@laravel.com',
    ]);

    $this->browse(function (Browser $browser) use ($user) {
        $browser->visit('/login')
                ->type('email', $user->email)
                ->type('password', 'password')
                ->press('Login')
                ->assertPathIs('/home');
    });
});
<?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' => 'taylor@laravel.com',
        ]);

        $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 方法进行 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
{
    /**
     * 注册 Dusk 的浏览器宏方法。
     */
    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 方法接受一个与您的可认证模型相关联的主键或一个可认证模型实例：

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

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

在使用 loginAs 方法后，用户会话将在文件中的所有测试中保持有效。

Cookies

您可以使用 cookie 方法来获取或设置加密的 cookie 值。默认情况下，Laravel 创建的所有 cookies 都是加密的：

$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');

您也可以传递一个包含多个 JavaScript 语句的数组：

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

如果需要获取执行结果，可以通过 script 方法返回的值：

$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 方法：

// 获取值...
$value = $browser->value('selector');

// 设置值...
$browser->value('selector', 'value');

您可以使用 inputValue 方法来获取具有给定字段名称的输入元素的 “值”：

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

检索文本

text 方法可用于检索匹配给定选择器的元素的显示文本：

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

检索属性

最后，attribute 方法可用于检索匹配给定选择器的元素的某个属性的值：

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

与表单交互

输入值

Dusk 提供了多种方法来与表单和输入元素进行交互。首先，让我们看一个将文本输入到输入框中的示例：

$browser->type('email', 'taylor@laravel.com');

注意，尽管该方法在必要时接受一个 CSS 选择器，但我们并不需要将 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 方法。与许多其它与输入相关的方法一样，check 方法不需要完整的 CSS 选择器。如果找不到匹配的 CSS 选择器，Dusk 会查找具有匹配名称属性的复选框：

$browser->check('terms');

uncheck 方法可用于取消勾选复选框输入框：

$browser->uncheck('terms');

单选按钮

要选择单选按钮选项，您可以使用 radio 方法。与许多其它与输入相关的方法一样，radio 方法不需要完整的 CSS 选择器。如果找不到匹配的 CSS 选择器，Dusk 会查找具有匹配 name 和 value 属性的单选按钮：

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

附加文件

attach 方法可用于将文件附加到 file 输入元素。与许多其它与输入相关的方法一样，attach 方法不需要完整的 CSS 选择器。如果找不到匹配的 CSS 选择器，Dusk 会查找具有匹配 name 属性的 file 输入框：

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

attach 函数需要在您的服务器上安装并启用 Zip PHP 扩展。

按下按钮

press 方法可用于点击页面上的按钮元素。传递给 press 方法的参数可以是按钮的显示文本，也可以是 CSS / Dusk 选择器：

$browser->press('Login');

在提交表单时，许多应用程序会在按钮被点击后禁用表单的提交按钮，并在表单提交的 HTTP 请求完成后重新启用该按钮。要点击按钮并等待按钮重新启用，可以使用 pressAndWaitFor 方法：

// 点击按钮并最多等待 5 秒钟，直到它被启用...
$browser->pressAndWaitFor('Save');

// 点击按钮并最多等待 1 秒钟，直到它被启用...
$browser->pressAndWaitFor('Save', 1);

点击链接

要点击链接，可以在浏览器实例上使用 clickLink 方法。clickLink 方法将点击具有给定显示文本的链接：

$browser->clickLink($linkText);

你可以使用 seeLink 方法来判断页面上是否可见具有给定显示文本的链接：

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

这些方法与 jQuery 交互。如果页面上没有 jQuery，Dusk 会自动将其注入到页面中，确保在测试过程中 jQuery 可用。

使用键盘

keys 方法允许你为给定元素提供比 type 方法更复杂的输入序列。例如，你可以指示 Dusk 在输入值时按住修饰键。在这个例子中，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 方法。通常，你应该在应用程序的 AppServiceProvider 的 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
{
    /**
     * 注册 Dusk 的浏览器宏。
     */
    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');

鼠标悬停

mouseover 方法可用于当你需要将鼠标移动到与给定 CSS 或 Dusk 选择器匹配的元素上时使用：

$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 对话框包含一个提示框（prompt），你可以使用 typeInDialog 方法在提示框中输入值：

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

要通过点击 "OK" 按钮关闭打开的 JavaScript 对话框，可以调用 acceptDialog 方法：

$browser->acceptDialog();

要通过点击 "Cancel" 按钮关闭打开的 JavaScript 对话框，可以调用 dismissDialog 方法：

$browser->dismissDialog();

与内嵌 Frame 交互

如果你需要与 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);

如果你需要在特定条件为真时暂停测试，可以使用 pauseIf 方法：

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

同样，如果你需要在特定条件为假时暂停测试，可以使用 pauseUnless 方法：

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

等待选择器

waitFor 方法用于暂停测试，直到匹配给定的 CSS 或 Dusk 选择器的元素显示在页面上。默认情况下，它会等待最多 5 秒，若超时则抛出异常。如果需要，你可以通过第二个参数设置自定义的超时阈值：

// 等待最多五秒钟，直到选择器显示...
$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 关键字或结尾的分号：

// 等待最多五秒钟，直到表达式为真...
$browser->waitUntil('App.data.servers.length > 0');

// 等待最多一秒钟，直到表达式为真...
$browser->waitUntil('App.data.servers.length > 0', 1);

等待 Vue 表达式

waitUntilVue 和 waitUntilVueIsNot 方法用于等待 Vue 组件 属性具有给定的值：

// 等待直到组件属性包含给定值...
$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 的 load 事件...
    $iframe->waitForEvent('load');
});

你还可以通过第二个参数向 waitForEvent 方法传递选择器，将事件监听器附加到特定元素：

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

你还可以等待 document 和 window 对象上的事件：

// 等待直到文档被滚动...
$browser->waitForEvent('scroll', 'document');

// 等待最多五秒钟，直到窗口被调整大小...
$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');

可用断言

TODO

页面

有时，测试需要执行多个复杂的操作序列，这可能使测试变得难以阅读和理解。Dusk 页面（Dusk Pages）允许你定义具有表现力的操作，然后通过单个方法在给定页面上执行这些操作。页面还允许你为应用程序或单个页面定义常用选择器的快捷方式。

生成页面

要生成一个页面对象，执行 dusk:page Artisan 命令。所有页面对象将被放置在你应用的 tests/Browser/Pages 目录中：

php artisan dusk:page Login

配置页面

默认情况下，页面对象有三个方法：url、assert 和 elements。我们现在将讨论 url 和 assert 方法，elements 方法将在下面更详细地讨论。

url 方法

url 方法应返回表示页面的 URL 路径。Dusk 会在浏览器中导航到该页面时使用此 URL：

/**
 * 获取页面的 URL。
 */
public function url(): string
{
    return '/login';
}

assert 方法

assert 方法可以执行任何必要的断言，以验证浏览器是否确实位于给定页面上。实际上，你不需要在此方法中放置任何内容；但是，如果需要，你可以在此方法中进行断言。这些断言将在导航到页面时自动执行：

/**
 * 断言浏览器当前在页面上。
 */
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" 输入框定义一个快捷方式：

/**
 * 获取页面的元素快捷方式。
 *
 * @return array<string, string>
 */
public function elements(): array
{
    return [
        '@email' => 'input[name=email]',
    ];
}

定义好快捷方式后，你可以像使用完整的 CSS 选择器一样，在任何地方使用这个简写选择器：

$browser->type('@email', 'taylor@laravel.com');

全局快捷选择器

安装 Dusk 后，tests/Browser/Pages 目录下会有一个基类 Page，该类包含一个 siteElements 方法，可以用来定义全局的快捷选择器，这些选择器将适用于你应用中的每个页面：

/**
 * 获取全站的元素快捷方式。
 *
 * @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
{
    // 其它页面方法...

    /**
     * 创建一个新的播放列表。
     */
    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
{
    /**
     * 获取组件的根选择器。
     */
    public function selector(): string
    {
        return '.date-picker';
    }

    /**
     * 断言浏览器页面包含该组件。
     */
    public function assert(Browser $browser): void
    {
        $browser->assertVisible($this->selector());
    }

    /**
     * 获取该组件的元素快捷方式。
     *
     * @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',
        ];
    }

    /**
     * 选择给定的日期。
     */
    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

  • PHPUnit

<?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');
    });
});
<?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 构建包和脚本添加到您的 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 内置的 web 服务器：

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 内置的 web 服务器：

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

# 在构建环境中包含 Chrome
services:
  - dusk

# 构建所有提交
on:
   push:
      branches: .*

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

      # 创建 dusk 环境文件，确保 APP_URL 使用 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 文档。