跳到主要内容
版本：10.x

Laravel Dusk

介绍​

Laravel Dusk 提供了一套富有表现力、易于使用的浏览器自动化和测试 API。默认情况下，Dusk 不需要在本地计算机上安装 JDK 或 Selenium。相反，Dusk 使用一个独立的 ChromeDriver 安装包。你可以自由地使用任何其他兼容 Selenium 的驱动程序。

安装​

为了开始使用，你需要先安装 Google Chrome 并将 laravel/dusk Composer 依赖添加到你的项目中：

composer require --dev laravel/dusk
注意

如果你手动注册 Dusk 的服务提供者，在生产环境中 绝不要 注册，因为这可能导致任意用户能够认证你的应用程序。

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

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。

使用数据库迁移​

DatabaseMigrations trait 会在每次测试之前运行你的数据库迁移。但是，为了每次测试而删除和重新创建数据库表通常比截断表要慢：

<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;
}
注意

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

使用数据库截断​

在使用 DatabaseTruncation trait 之前，你必须使用 Composer 包管理器安装 doctrine/dbal 包：

composer require --dev doctrine/dbal

DatabaseTruncation trait 将在第一次测试时迁移你的数据库，以确保你的数据库表已经被正确创建。但是，在后续测试中，数据库表将仅被截断 - 相比重新运行所有的数据库迁移，这样做可以提高速度：

<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseTruncation;
}

默认情况下，此 trait 将截断除 migrations 表以外的所有表。如果你想自定义应该截断的表，则可以在测试类上定义 $tablesToTruncate 属性：

/**
 * 表示应该截断哪些表。
 *
 * @var array
 */
protected $tablesToTruncate = ['users'];

或者，你可以在测试类上定义 $exceptTables 属性，以指定应该从截断中排除的表：

/**
 * 表示应该从截断中排除哪些表。
 *
 * @var array
 */
protected $exceptTables = ['users'];

为了指定需要清空表格的数据库连接，你可以在测试类中定义一个 $connectionsToTruncate 属性：

/**
 * 表示哪些连接需要清空表格。
 *
 * @var array
 */
protected $connectionsToTruncate = ['mysql'];

运行测试​

要运行浏览器测试，执行 dusk Artisan 命令：

php artisan dusk

如果上一次运行 dusk 命令时出现了测试失败，你可以通过 dusk:fails 命令先重新运行失败的测试，以节省时间：

php artisan dusk:fails

dusk 命令接受任何 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.{当前环境} 文件。例如，如果你将从你的 local 环境启动 dusk 命令，你应该创建一个 .env.dusk.local 文件。

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

浏览器基础知识​

创建浏览器​

为了开始学习，我们编写一个测试，验证我们能否登录到我们的应用程序。生成测试后，我们可以修改它以导航到登录页面，输入一些凭据并点击“登录”按钮。为了创建一个浏览器实例，你可以在 Dusk 测试中调用 browse 方法：

<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    /**
     * 一个基本的浏览器测试示例。
     */
    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 自动传递给此闭包，并且是与应用程序交互和进行断言的主要对象。

创建多个浏览器​

有时你可能需要多个浏览器来正确地进行测试。例如，测试与 WebSockets 交互的聊天屏幕可能需要多个浏览器。要创建多个浏览器，只需将更多的浏览器参数添加到传递给 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('login');

你可以使用 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方法接收用户 ID 或者用户模型实例

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

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

使用loginAs方法后，用户会话在文件中的所有测试被维护。

Cookies​

你可以使用cookie方法来获取或者设置加密过的 cookie 的值：

$browser->cookie('name');

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

使用plainCookie则可以获取或者设置未加密过的 cookie 的值：

$browser->plainCookie('name');

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

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

$browser->deleteCookie('name');

运行 JavaScript​

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

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

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

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

获取截图​

你可以使用screenshot方法来截图并将其指定文件名存储，所有截图都将存放在tests/Browser/screenshots目录下：

$browser->screenshot('filename');

responsiveScreenshots方法可用于在不同断点处截取一系列截图:

$browser->responsiveScreenshots('filename');

控制台输出结果保存到硬盘​

你可以使用storeConsoleLog方法将控制台输出指定文件名并写入磁盘，控制台输出默认存放在tests/Browser/console目录下：

$browser->storeConsoleLog('filename');

页面源码保存到硬盘​

你可以使用storeSource方法将页面当前源代码指定文件名并写入磁盘，页面源代码默认会存放到tests/Browser/source目录：

$browser->storeSource('filename');

与元素交互​

Dusk 选择器​

编写 Dusk 测试最困难的部分之一就是选择良好的 CSS 选择器与元素进行交互。 随着时间的推移，前端的更改可能会导致如下所示的 CSS 选择器无法通过测试：

// HTML...

<button>Login</button>

// Test...

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

Dusk 选择器可以让你专注于编写有效的测试，而不必记住 CSS 选择器。要定义一个选择器，你需要添加一个dusk属性在 HTML 元素中。然后在选择器前面加上@用来在 Dusk 测试中操作元素：

// HTML...

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

// Test...

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

文本、值 & 属性​

获取 & 设置值​

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 选择器传递给type方法。如果没有提供 CSS 选择器，Dusk 会搜索包含指定name属性的input或textarea字段。

要想将文本附加到一个字段之后而且不清除其内容， 你可以使用append方法：

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

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

$browser->clear('email');

你可以使用typeSlowly方法指示 Dusk 缓慢键入。 默认情况下，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方法。 类似于type方法， 该select方法并不是一定要传入 CSS 选择器。 当使用select方法时，你应该传递选项实际的值而不是它的显示文本：

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

你也可以通过省略第二个参数来随机选择一个选项：

$browser->select('size');

通过将数组作为select方法的第二个参数，可以指示该方法选择多个选项：

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

复选框​

使用「check」 复选框时，你可以使用check方法。 像其他许多与 input 相关的方法，并不是必须传入 CSS 选择器。 如果准确的选择器无法找到的时候，Dusk 会搜索能够与name属性匹配的复选框：

$browser->check('terms');

该uncheck方法可用于「取消选中」复选框输入：

$browser->uncheck('terms');

单选按钮​

使用 「select」中单选按钮选项时，你可以使用radio这个方法。 像很多其他的与输入相关的方法一样， 它也并不是必须传入 CSS 选择器。如果准确的选择器无法被找到的时候， Dusk 会搜索能够与name属性或者value属性相匹配的radio单选按钮：

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

附件​

该attach方法可以附加一个文件到fileinput 元素中。 像很多其他的与输入相关的方法一样，他也并不是必须传入 CSS 选择器。如果准确的选择器没有被找到的时候，Dusk 会搜索与name属性匹配的文件输入框：

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

attach 方法需要使用 PHPZip扩展，你的服务器必须安装了此扩展。

点击按钮​

可以使用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 会自动将其注入到页面中，以便在测试期间可用。

使用键盘​

该keys方法让你可以再指定元素中输入比type方法更加复杂的输入序列。例如，你可以在输入值的同时按下按键。在这个例子中，输入taylor时，shift键也同时被按下。当taylor输入完之后， 将会输入swift而不会按下任何按键：

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

keys方法的另一个有价值的用例是向你的应用程序的主要 CSS 选择器发送「键盘快捷键」组合：

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

所有修饰符键如{command}都包裹在{}字符中，并且与在 Facebook\WebDriver\WebDriverKeys类中定义的常量匹配，该类可以在 GitHub 上找到.

使用鼠标​

点击元素​

该click方法可用于「点击」与给定选择器匹配的元素：

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

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

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

该clickAtPoint方法可用于「点击」相对于浏览器可视区域的给定坐标对上的最高元素：

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

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

$browser->doubleClick();

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

$browser->rightClick();

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

该clickAndHold方法可用于模拟被单击并按住的鼠标按钮。 随后调用 releaseMouse 方法将撤消此行为并释放鼠标按钮：

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

鼠标悬停​

该mouseover方法可用于与给定选择器匹配的元素的鼠标悬停动作：

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

拖放​

该drag方法用于将与指定选择器匹配的元素拖到其它元素：

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

或者，可以在单一方向上拖动元素：

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

最后，你可以将元素拖动给定的偏移量：

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

JavaScript 对话框​

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

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

该assertDialogOpened方法，断言对话框已经显示，并且其消息与给定值匹配：

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

typeInDialog方法，在打开的 JavaScript 提示对话框中输入给定值：

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

acceptDialog方法，通过点击确定按钮关闭打开的 JavaScript 对话框：

$browser->acceptDialog();

dismissDialog方法，通过点击取消按钮关闭打开的 JavaScript 对话框（仅对确认对话框有效）：

$browser->dismissDialog();

选择器作用范围​

有时可能希望在给定的选择器范围内执行多个操作。比如，可能想要断言表格中存在某些文本，然后点击表格中的一个按钮。那么你可以使用with方法实现此需求。在传递给with方法的闭包内执行的所有操作都将限于原始选择器：

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

你可能偶尔需要在当前范围之外执行断言。 你可以使用elsewhere和elsewhereWhenAvailable方法来完成此操作：

 $browser->with('.table', function ($table) {
    // 当前范围是 `body .table`...

    $browser->elsewhere('.page-title', function ($title) {
        // 当前范围是 `body .page-title`...
        $title->assertSee('Hello World');
    });

    $browser->elsewhereWhenAvailable('.page-title', function ($title) {
        // 当前范围是 `body .page-title`...
        $title->assertSee('Hello World');
    });
 });

等待元素​

在测试大面积使用 JavaScript 的应用时，在进行测试之前，通常有必要 「等待」 某些元素或数据可用。Dusk 可轻松实现。使用一系列方法，可以等到页面元素可用，甚至给定的 JavaScript 表达式执行结果为true。

等待​

如果需要测试暂停指定的毫秒数， 使用pause方法：

$browser->pause(1000);

如果你只需要在给定条件为true时暂停测试，请使用pauseIf方法:

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

同样地，如果你需要暂停测试，除非给定的条件是true，你可以使用pauseUnless方法:

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

等待选择器​

该waitFor方法可以用于暂停执行测试，直到页面上与给定 CSS 选择器匹配的元素被显示。默认情况下，将在暂停超过 5 秒后抛出异常。如有必要，可以传递自定义超时时长作为其第二个参数：

// 等待选择器不超过 5 秒...
$browser->waitFor('.selector');

// 等待选择器不超过 1 秒...
$browser->waitFor('.selector', 1);

你也可以等待选择器显示给定文字：

//  等待选择器不超过 5 秒包含给定文字...
$browser->waitForTextIn('.selector', 'Hello World');

//  等待选择器不超过 1 秒包含给定文字...
$browser->waitForTextIn('.selector', 'Hello World', 1);

你也可以等待指定选择器从页面消失:

// 等待不超过 5 秒 直到选择器消失...
$browser->waitUntilMissing('.selector');

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

或者，你可以等待与给定选择器匹配的元素被启用或禁用：

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

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

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

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

限定作用域范围（可用时）​

有时，你或许希望等待给定选择器出现，然后与匹配选择器的元素进行交互。例如，你可能希望等到模态窗口可用，然后在模态窗口中点击「确定」按钮。在这种情况下，可以使用whenAvailable方法。给定回调内的所有要执行的元素操作都将被限定在起始选择器上:

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

等待文本​

waitForText方法可以用于等待页面上给定文字被显示：

// 等待指定文本不超过 5 秒...
$browser->waitForText('Hello World');

// 等待指定文本不超过 1 秒...
$browser->waitForText('Hello World', 1);

你可以使用waitUntilMissingText方法来等待，直到显示的文本已从页面中删除为止:

// 等待 5 秒删除文本...
$browser->waitUntilMissingText('Hello World');

// 等待 1 秒删除文本...
$browser->waitUntilMissingText('Hello World', 1);

waitForLink方法用于等待给定链接文字在页面上显示:

// 等待链接 5 秒...
$browser->waitForLink('Create');

// 等待链接 1 秒...
$browser->waitForLink('Create', 1);

等待输入​

waitForInput方法可用于等待，直到给定的输入字段在页面上可见:

// 等待 5 秒的输入…
$browser->waitForInput($field);

// 等待 1 秒的输入…
$browser->waitForInput($field, 1);

等待页面跳转​

当给出类似$browser->assertPathIs('/home')的路径断言时，如果window.location.pathname被异步更新，断言就会失败。可以使用waitForLocation方法等待页面跳转到给定路径：

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

waitForLocation方法还可用于等待当前窗口位置成为完全限定的 URL：

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

还可以使用被命名的路由等待跳转：

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

等待页面重新加载​

如果要在页面重新加载后断言，可以使用waitForReload方法：

use Laravel\Dusk\Browser;

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

由于需要等待页面重新加载通常发生在单击按钮之后，为了方便起见，你可以使用clickAndWaitForReload方法：

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

等待 JavaScript 表达式​

有时候会希望暂停测试的执行，直到给定的 JavaScript 表达式执行结果为true。可以使用waitUntil方法轻松地达成此目的。 通过这个方法执行表达式，不需要包含return关键字或者结束分号：

// 等待表达式为 true 5 秒时间...
$browser->waitUntil('App.data.servers.length > 0');

// 等待表达式为 true 1 秒时间...
$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 的加载事件…
    $iframe->waitForEvent('load');
});

你也可以提供一个选择器作为waitForEvent方法的第二个参数，将事件监听器附加到特定的元素上:

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

你也可以等待document和window对象上的事件:

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

// 等待 5 秒，直到窗口大小被调整…
$browser->waitForEvent('resize', 'window', 5);

等待回调​

Dusk 中的许多 「wait」 方法都依赖于底层方法 waitUsing。你可以直接用这个方法去等待一个回调函数返回waitUsing。你可以直接用这个方法去等待一个回调函数返回true。该waitUsing方法接收一个最大的等待秒数，闭包执行间隔时间，闭包，以及一个可选的失败信息：

$browser->waitUsing(10, 1, function () use ($something) {
    return $something->isReady();
}, "有些东西没有及时准备好。");

滚动元素到视图中​

有时你可能无法单击某个元素，因为该元素在浏览器的可见区域之外。该scrollIntoView方法可以将元素滚动到浏览器可视窗口内：

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

可用的断言​

Dusk 提供了各种你可以对应用使用的断言。所有可用的断言罗列如下：

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 assertIndeterminate 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​

断言页面标题为给定文本：

$browser->assertTitle($title);

assertTitleContains​

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

$browser->assertTitleContains($title);

assertUrlIs​

断言当前的 URL（不包含 query string）是给定的字符串：

$browser->assertUrlIs($url);

assertSchemeIs​

断言当前的 URL scheme 是给定的 scheme：

$browser->assertSchemeIs($scheme);

assertSchemeIsNot​

断言当前的 URL scheme 不是给定的 scheme：

$browser->assertSchemeIsNot($scheme);

assertHostIs​

断言当前的 URL host 是给定的 host：

$browser->assertHostIs($host);

assertHostIsNot​

断言当前的 URL host 不是给定的 host：

$browser->assertHostIsNot($host);

assertPortIs​

断言当前的 URL 端口是给定的端口：

$browser->assertPortIs($port);

assertPortIsNot​

断言当前的 URL 端口不是给定的端口：

$browser->assertPortIsNot($port);

assertPathBeginsWith​

断言当前的 URL 路径以给定的路径开始：

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

assertPathIs​

断言当前的路径是给定的路径：

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

assertPathIsNot​

断言当前的路径不是给定的路径：

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

assertRouteIs​

断言给定的 URL 是给定的命名路由的 URL:

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

assertQueryStringHas​

断言给定的查询字符串参数存在：

$browser->assertQueryStringHas($name);

断言给定的查询字符串参数存在并且具有给定的值：

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

assertQueryStringMissing​

断言缺少给定的查询字符串参数：

$browser->assertQueryStringMissing($name);

assertFragmentIs​

断言 URL 的当前哈希片段与给定的片段匹配：

$browser->assertFragmentIs('anchor');

assertFragmentBeginsWith​

断言 URL 的当前哈希片段以给定片段开头：

$browser->assertFragmentBeginsWith('anchor');

assertFragmentIsNot​

断言 URL 的当前哈希片段与给定的片段不匹配：

$browser->assertFragmentIsNot('anchor');

断言给定的加密 cookie 存在:

$browser->assertHasCookie($name);

断言给定的未加密 cookie 存在：

$browser->assertHasPlainCookie($name);

断言给定的加密 cookie 不存在：

$browser->assertCookieMissing($name);

断言给定的未加密 cookie 不存在：

$browser->assertPlainCookieMissing($name);

断言加密的 cookie 具有给定值：

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

断言未加密的 cookie 具有给定值：

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

assertSee​

断言在页面中有给定的文本：

$browser->assertSee($text);

assertDontSee​

断言在页面中没有给定的文本：

$browser->assertDontSee($text);

assertSeeIn​

断言在选择器中有给定的文本：

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

assertDontSeeIn​

断言在选择器中不存在给定的文本：

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

assertSeeAnythingIn​

断言在选择器中存在任意的文本：

$browser->assertSeeAnythingIn($selector);

断言在选择器中不存在文本：

$browser->assertSeeNothingIn($selector);

assertScript​

断言给定的 JavaScript 表达式结果为给定的值：

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

assertSourceHas​

断言在页面中存在给定的源码：

$browser->assertSourceHas($code);

assertSourceMissing​

断言页面中没有给定的源码：

$browser->assertSourceMissing($code);

断言在页面中存在指定的链接：

$browser->assertSeeLink($linkText);

断言页面中没有指定的链接：

$browser->assertDontSeeLink($linkText);

assertInputValue​

断言输入框（input）有给定的值：

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

assertInputValueIsNot​

断言输入框没有给定的值：

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

assertChecked​

断言复选框（checkbox）被选中：

$browser->assertChecked($field);

assertNotChecked​

断言复选框没有被选中：

$browser->assertNotChecked($field);

assertRadioSelected​

断言单选框（radio）被选中：

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

assertRadioNotSelected​

断言单选框（radio）没有被选中：

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

assertSelected​

断言下拉框有给定的值:

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

断言下拉框没有给定的值：

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

assertSelectHasOptions​

断言给定的数组值是可选的：

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

assertSelectMissingOptions​

断言给定的数组值是不可选的：

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

assertSelectHasOption​

断言给定的值在给定的地方是可供选择的：

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

assertSelectMissingOption​

断言给定的值不可选：

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

assertValue​

断言选择器范围内的元素存在指定的值：

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

assertValueIsNot​

断言选择器范围内的元素不存在指定的值：

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

assertAttribute​

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

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

assertAttributeContains​

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

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

assertAriaAttribute​

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

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

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

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

assertDataAttribute​

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

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

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

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

assertVisible​

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

$browser->assertVisible($selector);

assertPresent​

断言匹配给定选择器的元素存在：

$browser->assertPresent($selector);

assertNotPresent​

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

$browser->assertNotPresent($selector);

assertMissing​

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

$browser->assertMissing($selector);

assertInputPresent​

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

$browser->assertInputPresent($name);

assertInputMissing​

断言源中不存在具有给定名称的输入：

$browser->assertInputMissing($name);

assertDialogOpened​

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

$browser->assertDialogOpened($message);

assertEnabled​

断言给定的字段已启用：

$browser->assertEnabled($field);

assertDisabled​

断言给定的字段被禁用：

$browser->assertDisabled($field);

assertButtonEnabled​

断言给定的按钮已启用：

$browser->assertButtonEnabled($button);

assertButtonDisabled​

断言给定的按钮被禁用：

$browser->assertButtonDisabled($button);

assertFocused​

断言给定的字段是焦点：

$browser->assertFocused($field);

assertNotFocused​

断言给定字段未聚焦：

$browser->assertNotFocused($field);

assertAuthenticated​

断言用户已通过身份验证：

$browser->assertAuthenticated();

assertGuest​

断言用户未通过身份验证：

$browser->assertGuest();

assertAuthenticatedAs​

断言用户已作为给定用户进行身份验证：

$browser->assertAuthenticatedAs($user);

assertVue​

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

// HTML...

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

// 组件定义...

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

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

你可以像这样断言 Vue 组件的状态：

/**
 * 一个基本的 Vue 测试示例
 *
 * @return void
 */
public function testVue()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/')
                ->assertVue('user.name', 'Taylor', '@profile-component');
    });
}

assertVueIsNot​

断言 Vue 组件数据的属性不匹配给定的值：

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

assertVueContains​

断言 Vue 组件数据的属性是一个数组，并包含给定的值：

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

assertVueDoesNotContain​

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

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

Pages​

有时，测试需要按顺序执行几个复杂的操作。这会使测试代码更难阅读和理解。 Dusk Pages 允许你定义语义化的操作，然后可以通过单一方法在给定页面上执行这些操作。Pages 还可以为应用或单个页面定义通用选择器的快捷方式。

生成 Pages​

dusk:pageArtisan 命令可以生成页面对象。所有的页面对象都位于tests/Browser/Pages目录：

php artisan dusk:page Login

配置 Pages​

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

url 方法​

url方法应该返回表示页面 URL 的路径。 Dusk 将会在浏览器中使用这个 URL 来导航到具体页面：

/**
 * 获取页面的 URL。
 *
 * @return string
 */
public function url()
{
    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 之后，Page基类存放在你的tests/Browser/Pages目录。该类中包含一个siteElements方法，这个方法可以用来定义全局的选择器简写，这样在你应用中每个页面都可以使用这些全局选择器简写了：

/**
 * 获取站点全局的选择器简写。
 *
 * @return array<string, string>
 */
public static function siteElements(): array
{
    return [
        '@element' => '#selector',
    ];
}

页面方法​

除了页面中已经定义的默认方法之外，你还可以定义在整个测试过程中会使用到的其他方法。例如，假设我们正在开发一个音乐管理应用，在应用中每个页面都可能需要一个公共的方法来创建播放列表，而不是在每一个测试类中都重写一遍创建播放列表的逻辑，这时候你可以在你的页面类中定义一个createPlaylist方法：

<?php

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

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:componentArtisan 命令即可生成组件。新生成的组件位于tests/Browser/Components目录下：

php artisan dusk:component DatePicker

如上所示，这是生成一个「日期选择器」（date picker）组件的示例，这个组件可能会贯穿使用在你应用程序的许多页面中。在整个测试套件的大量测试页面中，手动编写日期选择的浏览器自动化逻辑会非常麻烦。 更方便的替代办法是，定义一个表示日期选择器的 Dusk 组件，然后把自动化逻辑封装在该组件内：

<?php

namespace Tests\Browser\Components;

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

class DatePicker extends BaseComponent
{
    /**
     * 获取组件的 root selector。
     */
    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);
                });
    }
}

使用组件​

当组件被定义了之后，我们就可以轻松的在任意测试页面通过日期选择器选择一个日期。并且，如果选择日期的逻辑发生了变化，我们只需要更新组件即可：

<?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
{
    /**
     * 一个基础的组件测试用例.
     */
    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 应用程序使用端口 8000 上的内置 PHP 开发服务器提供服务。因此，你应该确保持续集成环境有一个值为 http://127.0.0.1:8000 的 APP_URL 环境变量。

Heroku CI​

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

{
  "environments": {
    "test": {
      "buildpacks": [
        { "url": "heroku/php" },
        { "url": "https://github.com/heroku/heroku-buildpack-google-chrome" }
      ],
      "scripts": {
        "test-setup": "cp .env.testing .env",
        "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"
      }
    }
  }
}

Travis CI​

要在 Travis CI 运行 Dusk 测试，可以使用下面这个 .travis.yml 配置。由于 Travis CI 不是一个图形化的环境，我们还需要一些额外的步骤以便启动 Chrome 浏览器。此外，我们将会使用 php artisan serve 来启动 PHP 自带的 Web 服务器：

language: php

php:
  - 7.3

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@v3
      - 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 &
      - 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@v2
        with:
          name: screenshots
          path: tests/Browser/screenshots
      - name: Upload Console Logs
        if: failure()
        uses: actions/upload-artifact@v2
        with:
          name: console
          path: tests/Browser/console