Laravel Dusk

简介

WARNING

Pest 4 现已内置浏览器自动化测试，相比 Laravel Dusk 在性能和易用性上都有明显提升。对于新项目，建议优先使用 Pest 进行浏览器测试。

Laravel Dusk 提供了一个富有表现力且易于使用的浏览器自动化与测试 API。默认情况下，Dusk 不要求你在本地安装 JDK 或 Selenium。相反，Dusk 使用独立的 ChromeDriver 安装。不过，你也完全可以使用任何其他兼容 Selenium 的驱动。

安装

开始之前，你应先安装 Google Chrome，并将 laravel/dusk Composer 依赖加入项目：

shell

composer require laravel/dusk --dev

WARNING

如果你是手动注册 Dusk 的 service provider，绝不要在生产环境中注册它，否则可能导致任意用户能够通过你的应用进行身份认证。

安装 Dusk 包后，执行 dusk:install Artisan 命令。该命令会创建 tests/Browser 目录、一个示例 Dusk 测试，并为你的操作系统安装 Chrome Driver 二进制文件：

shell

php artisan dusk:install

接下来，在应用的 .env 文件中设置 APP_URL 环境变量。这个值应与你在浏览器中访问应用时使用的 URL 保持一致。

NOTE

如果你使用 Laravel Sail 管理本地开发环境，也请参阅 Sail 文档中关于配置与运行 Dusk 测试的部分。

管理 ChromeDriver 安装

如果你想安装与 dusk:install 命令默认安装版本不同的 ChromeDriver，可以使用 dusk:chrome-driver 命令：

shell

# 为当前操作系统安装最新版本的 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

WARNING

Dusk 要求 chromedriver 二进制文件具有可执行权限。如果你在运行 Dusk 时遇到问题，应确保通过以下命令为这些二进制文件赋予可执行权限：chmod -R 0755 vendor/laravel/dusk/bin/。

使用其他浏览器

默认情况下，Dusk 使用 Google Chrome 和独立的 ChromeDriver 安装来运行浏览器测试。不过，你也可以自行启动 Selenium 服务器，并针对任意浏览器运行测试。

首先，打开 tests/DuskTestCase.php 文件，它是你应用的基础 Dusk 测试用例。在这个文件中，你可以移除对 startChromeDriver 方法的调用。这样 Dusk 就不会自动启动 ChromeDriver：

php

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

接下来，你可以修改 driver 方法，使其连接到你指定的 URL 和端口。另外，你也可以修改应传递给 WebDriver 的 “desired capabilities”：

php

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 目录中：

shell

php artisan dusk:make LoginTest

每个测试后重置数据库

你编写的大多数测试都会与从应用数据库中读取数据的页面交互；不过，Dusk 测试绝不应使用 RefreshDatabase trait。RefreshDatabase trait 依赖数据库事务，而数据库事务无法跨 HTTP 请求生效。你有两个选择：DatabaseMigrations trait 与 DatabaseTruncation trait。

使用数据库迁移

DatabaseMigrations trait 会在每个测试前运行数据库迁移。不过，每次测试都删除并重新创建数据表，通常会比截断数据表更慢：

PestPHPUnit

php

<?php

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

pest()->use(DatabaseMigrations::class);

//

php

<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    //
}

WARNING

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

使用数据库截断

DatabaseTruncation trait 会在第一次测试时运行数据库迁移，以确保数据表已正确创建。而在后续测试中，只会对数据表进行截断，因此比重复运行所有迁移更快：

PestPHPUnit

php

<?php

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

pest()->use(DatabaseTruncation::class);

//

php

<?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 属性：

NOTE

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

php

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

或者，你也可以在测试类上定义 $exceptTables 属性，以指定哪些表应被排除在截断之外：

php

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

如果你想指定应对哪些数据库连接执行表截断，可以在测试类上定义 $connectionsToTruncate 属性：

php

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

如果你希望在执行数据库截断前后运行代码，可以在测试类上定义 beforeTruncatingDatabase 或 afterTruncatingDatabase 方法：

php

/**
 * 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 命令：

shell

php artisan dusk

如果你上一次运行 dusk 命令时有测试失败，可以使用 dusk:fails 命令优先重新运行失败测试，以节省时间：

shell

php artisan dusk:fails

dusk 命令接受任何 Pest / PHPUnit 测试运行器通常支持的参数，例如只运行某个指定分组的测试：

shell

php artisan dusk --group=foo

NOTE

如果你使用 Laravel Sail 管理本地开发环境，请参阅 Sail 文档中关于配置与运行 Dusk 测试的部分。

手动启动 ChromeDriver

默认情况下，Dusk 会自动尝试启动 ChromeDriver。如果这在你的系统上不起作用，可以在运行 dusk 命令之前手动启动 ChromeDriver。如果你选择手动启动 ChromeDriver，应将 tests/DuskTestCase.php 文件中的这一行注释掉：

php

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

此外，如果你是在 9515 以外的端口启动 ChromeDriver，则应修改同一个类中的 driver 方法，以反映正确端口：

php

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

PestPHPUnit

php

<?php

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

pest()->use(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

<?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 方法的闭包签名中增加浏览器参数：

php

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

php

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

你可以使用 visitRoute 方法跳转到命名路由：

php

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

你可以使用 back 和 forward 方法进行“后退”和“前进”导航：

php

$browser->back();

$browser->forward();

你可以使用 refresh 方法刷新页面：

php

$browser->refresh();

调整浏览器窗口大小

你可以使用 resize 方法来调整浏览器窗口大小：

php

$browser->resize(1920, 1080);

maximize 方法可用于最大化浏览器窗口：

php

$browser->maximize();

fitContent 方法会将浏览器窗口调整到与内容尺寸匹配：

php

$browser->fitContent();

当测试失败时，Dusk 会在截图前自动将浏览器尺寸调整为适应内容。你可以在测试中调用 disableFitOnFailure 方法来禁用这个功能：

php

$browser->disableFitOnFailure();

你可以使用 move 方法将浏览器窗口移动到屏幕上的其他位置：

php

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

浏览器宏

如果你想定义一个自定义浏览器方法，并在多个测试中复用，可以在 Browser 类上使用 macro 方法。通常，这个方法应在某个 service provider 的 boot 方法中调用：

php

<?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 实例上像调用方法一样调用这个宏时，宏闭包就会被执行：

php

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

身份认证

你经常会测试那些需要身份认证的页面。你可以使用 Dusk 的 loginAs 方法，避免在每个测试中都与登录页面交互。loginAs 方法接受与你的 authenticatable 模型关联的主键，或一个 authenticatable 模型实例：

php

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

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

WARNING

一旦使用 loginAs 方法，该用户会话将在当前文件中的所有测试里保持有效。

Cookie

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

php

$browser->cookie('name');

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

你可以使用 plainCookie 方法读取或设置未加密 cookie 的值：

php

$browser->plainCookie('name');

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

你可以使用 deleteCookie 方法删除指定 cookie：

php

$browser->deleteCookie('name');

执行 JavaScript

你可以使用 script 方法在浏览器中执行任意 JavaScript 语句：

php

$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 目录中：

php

$browser->screenshot('filename');

responsiveScreenshots 方法可用于在多个断点下连续截图：

php

$browser->responsiveScreenshots('filename');

screenshotElement 方法可用于对页面中的某个特定元素截图：

php

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

将控制台输出写入磁盘

你可以使用 storeConsoleLog 方法，将当前浏览器的控制台输出以指定文件名写入磁盘。控制台输出会存储在 tests/Browser/console 目录中：

php

$browser->storeConsoleLog('filename');

将页面源码写入磁盘

你可以使用 storeSource 方法，将当前页面源码以指定文件名写入磁盘。页面源码会存储在 tests/Browser/source 目录中：

php

$browser->storeSource('filename');

与元素交互

Dusk 选择器

为元素选择合适的 CSS 选择器，是编写 Dusk 测试最难的部分之一。随着前端不断变化，类似下面的 CSS 选择器很容易让测试失效：

html

// HTML...

<button>Login</button>

php

// Test...

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

Dusk 选择器让你可以专注于编写有效的测试，而不是记忆 CSS 选择器。要定义一个选择器，只需在 HTML 元素上添加 dusk 属性。然后，在 Dusk 浏览器中交互时，给选择器加上 @ 前缀，即可在测试中操作对应元素：

html

// HTML...

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

php

// Test...

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

如果需要，你也可以通过 selectorHtmlAttribute 方法自定义 Dusk 选择器使用的 HTML 属性。通常，这个方法应在应用 AppServiceProvider 的 boot 方法中调用：

php

use Laravel\Dusk\Dusk;

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

文本、值与属性

获取与设置值

Dusk 提供了多个方法，用于与页面元素的当前值、显示文本和属性交互。例如，要获取匹配某个 CSS 或 Dusk 选择器的元素 “value”，可以使用 value 方法：

php

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

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

你可以使用 inputValue 方法，获取具有指定字段名的 input 元素的 “value”：

php

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

获取文本

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

php

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

获取属性

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

php

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

与表单交互

输入值

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

php

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

注意，虽然必要时该方法也接受 CSS 选择器，但你并不一定要传入完整 CSS 选择器。如果未提供 CSS 选择器，Dusk 会查找具有给定 name 属性的 input 或 textarea 字段。

如果你想向字段追加文本，而不是先清空原有内容，可以使用 append 方法：

php

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

你可以使用 clear 方法清空输入值：

php

$browser->clear('email');

你可以使用 typeSlowly 方法让 Dusk 以较慢速度输入。默认情况下，Dusk 会在每次按键之间暂停 100 毫秒。要自定义按键间隔时间，可以将毫秒数作为第三个参数传入：

php

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

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

你也可以使用 appendSlowly 方法慢速追加文本：

php

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

下拉框

要选择 select 元素中的某个值，可以使用 select 方法。与 type 方法类似，select 方法也不要求你传入完整 CSS 选择器。向 select 方法传值时，应传入底层 option 的值，而不是显示文本：

php

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

省略第二个参数时，可以随机选择一个选项：

php

$browser->select('size');

如果将数组作为第二个参数传入 select 方法，则可以选择多个选项：

php

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

复选框

要勾选一个 checkbox 输入框，可以使用 check 方法。与许多其他输入相关方法一样，它不要求完整 CSS 选择器。如果找不到 CSS 选择器匹配，Dusk 会查找具有对应 name 属性的 checkbox：

php

$browser->check('terms');

uncheck 方法可用于取消勾选 checkbox：

php

$browser->uncheck('terms');

单选按钮

要选中某个 radio 输入项，可以使用 radio 方法。与许多其他输入相关方法一样，它不要求完整 CSS 选择器。如果找不到 CSS 选择器匹配，Dusk 会查找 name 和 value 属性都匹配的 radio 输入项：

php

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

附加文件

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

php

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

WARNING

attach 功能要求你的服务器已安装并启用 Zip PHP 扩展。

点击按钮

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

php

$browser->press('Login');

提交表单时，很多应用会在按钮被点击后先禁用提交按钮，等表单的 HTTP 请求完成后再重新启用。若要点击按钮并等待按钮恢复可用，可以使用 pressAndWaitFor 方法：

php

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

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

点击链接

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

php

$browser->clickLink($linkText);

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

php

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

WARNING

这些方法依赖 jQuery。如果页面中没有 jQuery，Dusk 会自动注入 jQuery，以便在测试期间使用。

使用键盘

keys 方法允许你为指定元素提供比 type 方法更复杂的输入序列。例如，你可以让 Dusk 在输入值时按住修饰键。下面这个例子中，输入 taylor 时会按住 shift 键；输入完 taylor 后，再在不按任何修饰键的情况下输入 swift：

php

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

keys 方法另一个有用的场景，是向应用的主 CSS 选择器发送“键盘快捷键”组合：

php

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

NOTE

所有像 {command} 这样的修饰键都包裹在 {} 中，并与 Facebook\WebDriver\WebDriverKeys 类中定义的常量对应，该类可以在 GitHub 上查看。

流式键盘交互

Dusk 还提供了 withKeyboard 方法，让你通过 Laravel\Dusk\Keyboard 类以流式方式执行复杂键盘交互。Keyboard 类提供了 press、release、type 和 pause 方法：

php

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

<?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 实例上像调用方法一样调用该宏时，宏闭包就会执行：

php

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

使用鼠标

点击元素

click 方法可用于点击与指定 CSS 或 Dusk 选择器匹配的元素：

php

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

clickAtXPath 方法可用于点击与给定 XPath 表达式匹配的元素：

php

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

clickAtPoint 方法可用于点击浏览器可视区域内、相对指定坐标上的最上层元素：

php

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

doubleClick 方法可用于模拟鼠标双击：

php

$browser->doubleClick();

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

rightClick 方法可用于模拟鼠标右击：

php

$browser->rightClick();

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

clickAndHold 方法可用于模拟按下并按住鼠标按钮。随后调用 releaseMouse 方法即可取消这一行为并释放鼠标按钮：

php

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

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

controlClick 方法可用于在浏览器中模拟 ctrl+click 事件：

php

$browser->controlClick();

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

鼠标悬停

如果你需要将鼠标移动到与指定 CSS 或 Dusk 选择器匹配的元素上，可以使用 mouseover 方法：

php

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

拖放

drag 方法可用于将与指定选择器匹配的元素拖动到另一个元素上：

php

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

或者，你也可以沿某个单独方向拖动元素：

php

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

最后，你还可以按指定偏移量拖动元素：

php

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

JavaScript 对话框

Dusk 提供了多种与 JavaScript 对话框交互的方法。例如，你可以使用 waitForDialog 方法等待 JavaScript 对话框出现。该方法接受一个可选参数，用于指定最多等待多少秒：

php

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

assertDialogOpened 方法可用于断言某个对话框已显示，并且包含指定消息：

php

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

如果 JavaScript 对话框中包含 prompt，你可以使用 typeInDialog 方法向其中输入值：

php

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

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

php

$browser->acceptDialog();

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

php

$browser->dismissDialog();

与内联框架交互

如果你需要与 iframe 内的元素交互，可以使用 withinFrame 方法。所有发生在传给 withinFrame 方法的闭包中的元素操作，都会被限定在指定 iframe 的上下文中：

php

$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 方法闭包中的所有操作，都会被限定在原始选择器作用域下：

php

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

你偶尔也可能需要跳出当前作用域来执行断言。你可以使用 elsewhere 和 elsewhereWhenAvailable 方法来实现：

php

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

php

$browser->pause(1000);

如果你只想在某个条件为 true 时暂停测试，可以使用 pauseIf 方法：

php

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

类似地，如果你想在某个条件不为 true 时暂停测试，可以使用 pauseUnless 方法：

php

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

等待选择器

waitFor 方法可用于暂停测试执行，直到与指定 CSS 或 Dusk 选择器匹配的元素出现在页面中。默认情况下，它最多等待五秒，然后抛出异常。如有需要，你也可以通过第二个参数传入自定义超时时间：

php

// 最多等待 5 秒，直到选择器出现...
$browser->waitFor('.selector');

// 最多等待 1 秒，直到选择器出现...
$browser->waitFor('.selector', 1);

你也可以等待匹配指定选择器的元素包含给定文本：

php

// 最多等待 5 秒，直到选择器包含指定文本...
$browser->waitForTextIn('.selector', 'Hello World');

// 最多等待 1 秒，直到选择器包含指定文本...
$browser->waitForTextIn('.selector', 'Hello World', 1);

你也可以等待匹配指定选择器的元素从页面中消失：

php

// 最多等待 5 秒，直到选择器消失...
$browser->waitUntilMissing('.selector');

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

或者，等待匹配指定选择器的元素变为启用或禁用状态：

php

// 最多等待 5 秒，直到选择器变为启用...
$browser->waitUntilEnabled('.selector');

// 最多等待 1 秒，直到选择器变为启用...
$browser->waitUntilEnabled('.selector', 1);

// 最多等待 5 秒，直到选择器变为禁用...
$browser->waitUntilDisabled('.selector');

// 最多等待 1 秒，直到选择器变为禁用...
$browser->waitUntilDisabled('.selector', 1);

在元素可用时限定作用域

有时你会想等待某个匹配指定选择器的元素出现，然后立刻与之交互。例如，你可能需要等一个模态框出现后，在其中点击 “OK” 按钮。这种情况下可以使用 whenAvailable 方法。闭包中的所有元素操作都会限定在原始选择器作用域中：

php

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

等待文本

waitForText 方法可用于等待指定文本出现在页面中：

php

// 最多等待 5 秒，直到文本出现...
$browser->waitForText('Hello World');

// 最多等待 1 秒，直到文本出现...
$browser->waitForText('Hello World', 1);

你可以使用 waitUntilMissingText 方法来等待显示文本从页面中消失：

php

// 最多等待 5 秒，直到文本被移除...
$browser->waitUntilMissingText('Hello World');

// 最多等待 1 秒，直到文本被移除...
$browser->waitUntilMissingText('Hello World', 1);

等待链接

waitForLink 方法可用于等待指定链接文本出现在页面中：

php

// 最多等待 5 秒，直到链接出现...
$browser->waitForLink('Create');

// 最多等待 1 秒，直到链接出现...
$browser->waitForLink('Create', 1);

等待输入框

waitForInput 方法可用于等待指定输入字段在页面中可见：

php

// 最多等待 5 秒，直到输入框出现...
$browser->waitForInput($field);

// 最多等待 1 秒，直到输入框出现...
$browser->waitForInput($field, 1);

等待页面位置

执行路径断言，例如 $browser->assertPathIs('/home') 时，如果 window.location.pathname 是异步更新的，断言就可能失败。你可以使用 waitForLocation 方法，等待当前位置变为指定值：

php

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

waitForLocation 方法同样可用于等待当前窗口位置变成完整 URL：

php

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

你也可以等待某个命名路由对应的位置：

php

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

等待页面重载

如果你需要在某个操作之后等待页面重新加载，可以使用 waitForReload 方法：

php

use Laravel\Dusk\Browser;

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

由于等待页面重载通常发生在点击按钮之后，因此你也可以直接使用更方便的 clickAndWaitForReload 方法：

php

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

等待 JavaScript 表达式

有时你可能希望暂停测试执行，直到某个 JavaScript 表达式求值为 true。使用 waitUntil 方法可以轻松实现。向该方法传入表达式时，无需包含 return 关键字，也不需要结尾分号：

php

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

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

等待 Vue 表达式

waitUntilVue 与 waitUntilVueIsNot 方法可用于等待某个 Vue 组件属性拥有指定值：

php

// 等待组件属性包含指定值...
$browser->waitUntilVue('user.name', 'Taylor', '@user');

// 等待组件属性不再包含指定值...
$browser->waitUntilVueIsNot('user.name', null, '@user');

等待 JavaScript 事件

waitForEvent 方法可用于暂停测试执行，直到某个 JavaScript 事件发生：

php

$browser->waitForEvent('load');

事件监听器默认会附加到当前作用域，即 body 元素。当你使用了作用域选择器后，事件监听器会附加到匹配元素上：

php

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

你也可以将选择器作为 waitForEvent 方法的第二个参数传入，将监听器附加到指定元素：

php

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

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

php

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

// 最多等待 5 秒，直到窗口尺寸被改变...
$browser->waitForEvent('resize', 'window', 5);

使用回调等待

Dusk 中许多 “wait” 方法都依赖底层的 waitUsing 方法。你也可以直接使用它，等待某个闭包返回 true。waitUsing 方法接受最大等待秒数、闭包的检查间隔、闭包本身，以及一个可选失败消息：

php

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

将元素滚动到可视区域

有时你可能无法点击某个元素，因为它位于浏览器可视区域之外。scrollIntoView 方法会滚动浏览器窗口，直到指定选择器对应的元素进入视口：

php

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

可用断言

Dusk 提供了大量可用于对应用执行断言的方法。所有可用断言如下：

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

assertTitle

断言页面标题与给定文本完全匹配：

php

$browser->assertTitle($title);

assertTitleContains

断言页面标题包含给定文本：

php

$browser->assertTitleContains($title);

assertUrlIs

断言当前 URL（不含查询字符串）与给定字符串匹配：

php

$browser->assertUrlIs($url);

assertSchemeIs

断言当前 URL 的 scheme 与给定值匹配：

php

$browser->assertSchemeIs($scheme);

assertSchemeIsNot

断言当前 URL 的 scheme 不与给定值匹配：

php

$browser->assertSchemeIsNot($scheme);

assertHostIs

断言当前 URL 的 host 与给定值匹配：

php

$browser->assertHostIs($host);

assertHostIsNot

断言当前 URL 的 host 不与给定值匹配：

php

$browser->assertHostIsNot($host);

assertPortIs

断言当前 URL 的端口与给定值匹配：

php

$browser->assertPortIs($port);

assertPortIsNot

断言当前 URL 的端口不与给定值匹配：

php

$browser->assertPortIsNot($port);

assertPathBeginsWith

断言当前 URL 路径以前缀路径开始：

php

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

assertPathEndsWith

断言当前 URL 路径以后缀路径结束：

php

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

assertPathContains

断言当前 URL 路径包含给定路径：

php

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

assertPathIs

断言当前路径与给定路径完全匹配：

php

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

assertPathIsNot

断言当前路径不与给定路径匹配：

php

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

assertRouteIs

断言当前 URL 与给定命名路由生成的 URL 匹配：

php

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

assertQueryStringHas

断言查询字符串中存在指定参数：

php

$browser->assertQueryStringHas($name);

断言查询字符串中存在指定参数，且其值为给定值：

php

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

assertQueryStringMissing

断言查询字符串中不存在指定参数：

php

$browser->assertQueryStringMissing($name);

assertFragmentIs

断言 URL 当前 hash fragment 与给定值匹配：

php

$browser->assertFragmentIs('anchor');

assertFragmentBeginsWith

断言 URL 当前 hash fragment 以前缀值开始：

php

$browser->assertFragmentBeginsWith('anchor');

assertFragmentIsNot

断言 URL 当前 hash fragment 不与给定值匹配：

php

$browser->assertFragmentIsNot('anchor');

断言指定加密 cookie 存在：

php

$browser->assertHasCookie($name);

断言指定未加密 cookie 存在：

php

$browser->assertHasPlainCookie($name);

断言指定加密 cookie 不存在：

php

$browser->assertCookieMissing($name);

断言指定未加密 cookie 不存在：

php

$browser->assertPlainCookieMissing($name);

断言某个加密 cookie 的值与给定值匹配：

php

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

断言某个未加密 cookie 的值与给定值匹配：

php

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

assertSee

断言页面中包含给定文本：

php

$browser->assertSee($text);

assertDontSee

断言页面中不包含给定文本：

php

$browser->assertDontSee($text);

assertSeeIn

断言给定选择器内包含给定文本：

php

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

assertDontSeeIn

断言给定选择器内不包含给定文本：

php

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

assertSeeAnythingIn

断言给定选择器内存在任意文本：

php

$browser->assertSeeAnythingIn($selector);

assertSeeNothingIn

断言给定选择器内不存在任何文本：

php

$browser->assertSeeNothingIn($selector);

assertCount

断言与给定选择器匹配的元素出现次数等于指定值：

php

$browser->assertCount($selector, $count);

assertScript

断言给定 JavaScript 表达式的求值结果等于给定值：

php

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

assertSourceHas

断言页面源码中包含给定代码：

php

$browser->assertSourceHas($code);

assertSourceMissing

断言页面源码中不包含给定代码：

php

$browser->assertSourceMissing($code);

assertSeeLink

断言页面中存在给定链接：

php

$browser->assertSeeLink($linkText);

assertDontSeeLink

断言页面中不存在给定链接：

php

$browser->assertDontSeeLink($linkText);

assertInputValue

断言给定输入字段的值等于给定值：

php

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

assertInputValueIsNot

断言给定输入字段的值不等于给定值：

php

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

assertChecked

断言给定 checkbox 处于选中状态：

php

$browser->assertChecked($field);

assertNotChecked

断言给定 checkbox 未被选中：

php

$browser->assertNotChecked($field);

assertIndeterminate

断言给定 checkbox 处于 indeterminate 状态：

php

$browser->assertIndeterminate($field);

assertRadioSelected

断言给定 radio 字段已选中指定值：

php

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

assertRadioNotSelected

断言给定 radio 字段未选中指定值：

php

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

assertSelected

断言给定下拉框已选中指定值：

php

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

assertNotSelected

断言给定下拉框未选中指定值：

php

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

assertSelectHasOptions

断言给定数组中的值都可被该字段选择：

php

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

assertSelectMissingOptions

断言给定数组中的值都不可被该字段选择：

php

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

assertSelectHasOption

断言给定字段中存在可选的指定值：

php

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

assertSelectMissingOption

断言给定字段中不存在可选的指定值：

php

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

assertValue

断言与给定选择器匹配的元素拥有指定值：

php

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

assertValueIsNot

断言与给定选择器匹配的元素不拥有指定值：

php

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

assertAttribute

断言与给定选择器匹配的元素在指定属性中拥有给定值：

php

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

assertAttributeMissing

断言与给定选择器匹配的元素缺少指定属性：

php

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

assertAttributeContains

断言与给定选择器匹配的元素在指定属性中包含给定值：

php

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

assertAttributeDoesntContain

断言与给定选择器匹配的元素在指定属性中不包含给定值：

php

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

assertAriaAttribute

断言与给定选择器匹配的元素在指定 aria 属性中拥有给定值：

php

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

例如，给定标记 <button aria-label="Add"></button>，你可以像下面这样断言 aria-label 属性：

php

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

assertDataAttribute

断言与给定选择器匹配的元素在指定 data 属性中拥有给定值：

php

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

例如，给定标记 <tr id="row-1" data-content="attendees"></tr>，你可以像下面这样断言 data-label 属性：

php

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

assertVisible

断言与给定选择器匹配的元素可见：

php

$browser->assertVisible($selector);

assertPresent

断言与给定选择器匹配的元素存在于源码中：

php

$browser->assertPresent($selector);

assertNotPresent

断言与给定选择器匹配的元素不存在于源码中：

php

$browser->assertNotPresent($selector);

assertMissing

断言与给定选择器匹配的元素不可见：

php

$browser->assertMissing($selector);

assertInputPresent

断言具有给定名称的 input 存在：

php

$browser->assertInputPresent($name);

assertInputMissing

断言具有给定名称的 input 不存在于源码中：

php

$browser->assertInputMissing($name);

assertDialogOpened

断言给定消息的 JavaScript 对话框已经打开：

php

$browser->assertDialogOpened($message);

assertEnabled

断言给定字段处于启用状态：

php

$browser->assertEnabled($field);

assertDisabled

断言给定字段处于禁用状态：

php

$browser->assertDisabled($field);

assertButtonEnabled

断言给定按钮处于启用状态：

php

$browser->assertButtonEnabled($button);

assertButtonDisabled

断言给定按钮处于禁用状态：

php

$browser->assertButtonDisabled($button);

assertFocused

断言给定字段已获得焦点：

php

$browser->assertFocused($field);

assertNotFocused

断言给定字段未获得焦点：

php

$browser->assertNotFocused($field);

assertAuthenticated

断言用户已通过认证：

php

$browser->assertAuthenticated();

assertGuest

断言用户未通过认证：

php

$browser->assertGuest();

assertAuthenticatedAs

断言当前认证用户就是给定用户：

php

$browser->assertAuthenticatedAs($user);

assertVue

Dusk 甚至允许你对 Vue 组件数据状态执行断言。例如，假设你的应用包含如下 Vue 组件：

// HTML...

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

// Component Definition...

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

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

你可以像下面这样对 Vue 组件的状态执行断言：

PestPHPUnit

php

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

php

/**
 * 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 组件数据属性不等于给定值：

php

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

assertVueContains

断言某个 Vue 组件数据属性是数组，且包含给定值：

php

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

assertVueDoesntContain

断言某个 Vue 组件数据属性是数组，且不包含给定值：

php

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

页面对象

有时，测试需要按顺序执行多个复杂操作。这会让测试更难阅读和理解。Dusk 的 Page 对象允许你定义富有表现力的操作，然后通过单个方法在给定页面上执行。Page 还允许你为应用中常见的选择器或某个页面专门定义快捷方式。

生成页面对象

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

shell

php artisan dusk:page Login

配置页面对象

默认情况下，页面对象有三个方法：url、assert 和 elements。下面先介绍 url 与 assert。elements 方法会在快捷选择器一节中详细说明。

`url` 方法

url 方法应返回代表该页面的 URL 路径。Dusk 会在浏览器跳转到该页面时使用这个 URL：

php

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

`assert` 方法

assert 方法可执行任何必要断言，以验证浏览器当前确实位于该页面。实际上，这个方法中不一定非要写内容；不过，如果你愿意，也完全可以在这里加入断言。当导航到这个页面时，这些断言会自动执行：

php

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

跳转到页面对象

定义好页面对象后，你就可以使用 visit 方法跳转到它：

php

use Tests\Browser\Pages\Login;

$browser->visit(new Login);

有时你可能已经位于某个页面上，但需要将该页面的选择器和方法“加载”进当前测试上下文。这种情况常见于点击某个按钮后被重定向到某页面，但并非显式导航过去。此时，你可以使用 on 方法来加载该页面：

php

use Tests\Browser\Pages\CreatePlaylist;

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

快捷选择器

页面类中的 elements 方法允许你为页面上的任意 CSS 选择器定义易记且快速的快捷方式。例如，下面我们为应用登录页的 “email” 输入框定义一个快捷方式：

php

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

定义好快捷方式后，你就可以在任何原本需要完整 CSS 选择器的地方使用这个简写：

php

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

全局快捷选择器

安装 Dusk 后，tests/Browser/Pages 目录下会生成一个基础 Page 类。这个类包含 siteElements 方法，你可以用它来定义在整个应用每个页面上都可用的全局快捷选择器：

php

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

页面方法

除了页面对象默认定义的方法外，你还可以定义其他方法，并在测试中复用。例如，假设我们正在构建一个音乐管理应用。对于某个页面，一个常见操作可能是创建播放列表。与其在每个测试里都重写创建播放列表的逻辑，不如在页面类上定义 createPlaylist 方法：

php

<?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');
    }
}

方法定义完成后，就可以在任何使用该页面对象的测试中调用它。浏览器实例会自动作为第一个参数传给自定义页面方法：

php

use Tests\Browser\Pages\Dashboard;

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

组件

组件与 Dusk 的 “page object” 类似，但它更适合表示在整个应用中反复出现的 UI 和功能片段，例如导航栏或通知窗口。因此，组件不会绑定到特定 URL。

生成组件

要生成组件，请执行 dusk:component Artisan 命令。新组件会被放在 tests/Browser/Components 目录中：

shell

php artisan dusk:component DatePicker

如上所示，“日期选择器”就是一个可能在应用多个页面中反复出现的组件示例。如果你在整个测试套件的几十个测试里都手动编写选择日期的浏览器自动化逻辑，会非常繁琐。相反，我们可以定义一个 Dusk 组件来表示日期选择器，并把相关逻辑封装在组件内部：

php

<?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);
            });
    }
}

使用组件

定义好组件后，我们就可以在任意测试中轻松通过日期选择器选择日期。如果选择日期所需的逻辑发生变化，我们也只需要更新这个组件即可：

PestPHPUnit

php

<?php

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

pest()->use(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

<?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');
        });
    }
}

你可以使用 component 方法来获取一个作用域限定到指定组件的浏览器实例：

php

$datePicker = $browser->component(new DatePickerComponent);

$datePicker->selectDate(2019, 1, 30);

$datePicker->assertSee('January');

持续集成

WARNING

大多数 Dusk 持续集成配置都默认你的 Laravel 应用会通过 PHP 内置开发服务器运行在 8000 端口上。因此，在继续之前，请确保你的持续集成环境中 APP_URL 环境变量的值为 http://127.0.0.1:8000。

Heroku CI

要在 Heroku CI 上运行 Dusk 测试，请将以下 Google Chrome buildpack 和脚本加入 Heroku 的 app.json 文件：

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 服务器：

yaml

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 测试，可以以下面的配置文件作为起点。与 Travis CI 类似，我们将使用 php artisan serve 命令来启动 PHP 内置 Web 服务器：

yaml

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@v5
      - 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，以便监听请求：

yaml

# 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

      # 创建 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 官方文档。

Laravel Dusk ​

简介 ​

安装 ​

管理 ChromeDriver 安装 ​

使用其他浏览器 ​

快速开始 ​

生成测试 ​

每个测试后重置数据库 ​

使用数据库迁移 ​

使用数据库截断 ​

运行测试 ​

手动启动 ChromeDriver ​

环境处理 ​

浏览器基础 ​

创建浏览器实例 ​

创建多个浏览器实例 ​

页面导航 ​

调整浏览器窗口大小 ​

浏览器宏 ​

身份认证 ​

Cookie ​

执行 JavaScript ​

截图 ​

将控制台输出写入磁盘 ​

将页面源码写入磁盘 ​

与元素交互 ​

Dusk 选择器 ​

文本、值与属性 ​

获取与设置值 ​

获取文本 ​

获取属性 ​

与表单交互 ​

输入值 ​

下拉框 ​

复选框 ​

单选按钮 ​

附加文件 ​

点击按钮 ​

点击链接 ​

使用键盘 ​

流式键盘交互 ​

键盘宏 ​

使用鼠标 ​

点击元素 ​

鼠标悬停 ​

拖放 ​

JavaScript 对话框 ​

与内联框架交互 ​

限定选择器作用域 ​

等待元素 ​

等待 ​

等待选择器 ​

在元素可用时限定作用域 ​

等待文本 ​

等待链接 ​

等待输入框 ​

等待页面位置 ​

等待页面重载 ​

等待 JavaScript 表达式 ​

等待 Vue 表达式 ​

等待 JavaScript 事件 ​

使用回调等待 ​

将元素滚动到可视区域 ​

可用断言 ​

assertTitle ​

assertTitleContains ​

assertUrlIs ​

assertSchemeIs ​

assertSchemeIsNot ​

assertHostIs ​

assertHostIsNot ​

assertPortIs ​

assertPortIsNot ​

assertPathBeginsWith ​

assertPathEndsWith ​

assertPathContains ​

assertPathIs ​

assertPathIsNot ​

assertRouteIs ​

assertQueryStringHas ​

Laravel Dusk

简介

安装

管理 ChromeDriver 安装

使用其他浏览器

快速开始

生成测试

每个测试后重置数据库

使用数据库迁移

使用数据库截断

运行测试

手动启动 ChromeDriver

环境处理

浏览器基础

创建浏览器实例

创建多个浏览器实例

页面导航

调整浏览器窗口大小

浏览器宏

身份认证

Cookie

执行 JavaScript

截图

将控制台输出写入磁盘

将页面源码写入磁盘

与元素交互

Dusk 选择器

文本、值与属性

获取与设置值

获取文本

获取属性

与表单交互

输入值

下拉框

复选框

单选按钮

附加文件

点击按钮

点击链接

使用键盘

流式键盘交互

键盘宏

使用鼠标

点击元素

鼠标悬停

拖放

JavaScript 对话框

与内联框架交互

限定选择器作用域

等待元素

等待

等待选择器

在元素可用时限定作用域

等待文本

等待链接

等待输入框

等待页面位置

等待页面重载

等待 JavaScript 表达式

等待 Vue 表达式

等待 JavaScript 事件

使用回调等待

将元素滚动到可视区域

可用断言

assertTitle

assertTitleContains

assertUrlIs

assertSchemeIs

assertSchemeIsNot

assertHostIs

assertHostIsNot

assertPortIs

assertPortIsNot

assertPathBeginsWith

assertPathEndsWith

assertPathContains

assertPathIs

assertPathIsNot

assertRouteIs

assertQueryStringHas