Laravel 中文文档

主题

全部文档

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 的服务提供者，则绝对不要在生产环境中注册它，因为这样做可能会导致任意用户能够通过你的应用程序进行身份验证。

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

shell
php artisan dusk:install

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

INFO

如果你使用 Laravel Sail 管理本地开发环境，另请参阅有关 configuring and running Dusk tests 的 Sail 文档。

管理 ChromeDriver 安装 ​

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

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

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

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

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

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 的「所需功能」：

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 特征。 RefreshDatabase 特征利用数据库事务，该事务在 HTTP 请求中不适用或不可用。相反，你有两个选择：DatabaseMigrations 特征和 DatabaseTruncation 特征。

使用数据库迁移 ​

DatabaseMigrations 特征将在每次测试之前运行数据库迁移。但是，为每个测试删除并重新创建数据库表通常比截断表慢：

php
<?php

use Illuminate\Foundation\Testing\DatabaseMigrations;

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 特征将在第一次测试时迁移你的数据库，以确保你的数据库表已正确创建。但是，在后续测试中，数据库的表将被简单地截断 - 与重新运行所有数据库迁移相比，速度会得到提升：

php
<?php

use Illuminate\Foundation\Testing\DatabaseTruncation;

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;

    //
}

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

INFO

如果你使用 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 测试运行程序通常接受的任何参数，例如允许你仅运行给定 group 的测试：

shell
php artisan dusk --group=foo

INFO

如果你使用 Laravel Sail 管理本地开发环境，请参阅有关 configuring and running Dusk tests 的 Sail 文档。

手动启动 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 文件将被恢复。

浏览器基础知识 ​

创建浏览器 ​

首先，让我们编写一个测试来验证我们是否可以登录我们的应用程序。生成测试后，我们可以对其进行修改以导航到登录页面，输入一些凭据，然后单击「登录」按钮。要创建浏览器实例，你可以在 Dusk 测试中调用 browse 方法：

php
<?php

use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;

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 方法导航到 named route：

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's 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 方法接受与你的可验证模型或可验证模型实例关联的主键：

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

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

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

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

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 选择器传递到 type 方法中。如果未提供 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 方法时，你应该传递基础选项值而不是显示文本：

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

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

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

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

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

复选框 ​

要「检查」复选框输入，你可以使用 check 方法。与许多其他输入相关的方法一样，不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配，Dusk 将搜索具有匹配的 name 属性的复选框：

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

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

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

附加功能需要在你的服务器上安装并启用 Zip PHP 扩展。

按下按钮 ​

press 方法可用于单击页面上的按钮元素。提供给 press 方法的参数可以是按钮的显示文本或 CSS / Dusk 选择器：

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

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

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

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

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

php
$browser->clickLink($linkText);

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

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

WARNING

这些方法与 jQuery 交互。如果 jQuery 在页面上不可用，Dusk 会自动将其注入到页面中，以便在测试期间可用。

使用键盘 ​

keys 方法允许你向给定元素提供比 type 方法通常允许的更复杂的输入序列。例如，你可以指示 Dusk 在输入值时按住修饰键。在此示例中，在将 taylor 输入到与给定选择器匹配的元素中时，将按住 shift 键。键入 taylor 后，将键入 swift，无需任何修饰键：

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

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

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

INFO

所有修饰键（例如 {command}）都包含在 {} 字符中，并与 Facebook\WebDriver\WebDriverKeys 类中定义的常量匹配，该常量可以是 found on 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's 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 对话框包含提示，你可以使用 typeInDialog 方法在提示中键入一个值：

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

要通过单击「确定」按钮关闭打开的 JavaScript 对话框，你可以调用 acceptDialog 方法：

php
$browser->acceptDialog();

要通过单击「取消」按钮关闭打开的 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) {
    // Current scope is `body .table`...

    $browser->elsewhere('.page-title', function (Browser $title) {
        // Current scope is `body .page-title`...
        $title->assertSee('Hello World');
    });

    $browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
        // Current scope is `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
// Wait a maximum of five seconds for the selector...
$browser->waitFor('.selector');

// Wait a maximum of one second for the selector...
$browser->waitFor('.selector', 1);

你还可以等到与给定选择器匹配的元素包含给定文本：

php
// Wait a maximum of five seconds for the selector to contain the given text...
$browser->waitForTextIn('.selector', 'Hello World');

// Wait a maximum of one second for the selector to contain the given text...
$browser->waitForTextIn('.selector', 'Hello World', 1);

你也可以等到页面中缺少与给定选择器匹配的元素：

php
// Wait a maximum of five seconds until the selector is missing...
$browser->waitUntilMissing('.selector');

// Wait a maximum of one second until the selector is missing...
$browser->waitUntilMissing('.selector', 1);

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

php
// Wait a maximum of five seconds until the selector is enabled...
$browser->waitUntilEnabled('.selector');

// Wait a maximum of one second until the selector is enabled...
$browser->waitUntilEnabled('.selector', 1);

// Wait a maximum of five seconds until the selector is disabled...
$browser->waitUntilDisabled('.selector');

// Wait a maximum of one second until the selector is disabled...
$browser->waitUntilDisabled('.selector', 1);

范围选择器（如果可用） ​

有时，你可能希望等待与给定选择器匹配的元素出现，然后与该元素进行交互。例如，你可能希望等到模态窗口可用，然后按模态中的「确定」按钮。可以使用 whenAvailable 方法来完成此操作。在给定闭包内执行的所有元素操作都将限定在原始选择器范围内：

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

等待短信 ​

waitForText 方法可用于等待给定文本显示在页面上：

php
// Wait a maximum of five seconds for the text...
$browser->waitForText('Hello World');

// Wait a maximum of one second for the text...
$browser->waitForText('Hello World', 1);

你可以使用 waitUntilMissingText 方法等待显示的文本从页面中删除：

php
// Wait a maximum of five seconds for the text to be removed...
$browser->waitUntilMissingText('Hello World');

// Wait a maximum of one second for the text to be removed...
$browser->waitUntilMissingText('Hello World', 1);

waitForLink 方法可用于等待给定的链接文本显示在页面上：

php
// Wait a maximum of five seconds for the link...
$browser->waitForLink('Create');

// Wait a maximum of one second for the link...
$browser->waitForLink('Create', 1);

等待输入 ​

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

php
// Wait a maximum of five seconds for the input...
$browser->waitForInput($field);

// Wait a maximum of one second for the input...
$browser->waitForInput($field, 1);

等待页面位置 ​

在进行诸如 $browser->assertPathIs('/home') 之类的路径断言时，如果 window.location.pathname 异步更新，断言可能会失败。你可以使用 waitForLocation 方法等待位置为给定值：

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

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

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

你还可以等待 named route's 位置：

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
// Wait a maximum of five seconds for the expression to be true...
$browser->waitUntil('App.data.servers.length > 0');

// Wait a maximum of one second for the expression to be true...
$browser->waitUntil('App.data.servers.length > 0', 1);

等待 Vue 表达式 ​

waitUntilVue 和 waitUntilVueIsNot 方法可用于等待 Vue component 属性具有给定值：

php
// Wait until the component attribute contains the given value...
$browser->waitUntilVue('user.name', 'Taylor', '@user');

// Wait until the component attribute doesn't contain the given value...
$browser->waitUntilVueIsNot('user.name', null, '@user');

等待 JavaScript 事件 ​

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

php
$browser->waitForEvent('load');

事件侦听器附加到当前范围，默认情况下为 body 元素。当使用作用域选择器时，事件监听器将附加到匹配的元素：

php
$browser->with('iframe', function (Browser $iframe) {
    // Wait for the iframe's load event...
    $iframe->waitForEvent('load');
});

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

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

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

php
// Wait until the document is scrolled...
$browser->waitForEvent('scroll', 'document');

// Wait a maximum of five seconds until the window is resized...
$browser->waitForEvent('resize', 'window', 5);

等待回调 ​

Dusk 中的许多「等待」方法都依赖于底层的 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 提供了你可以针对你的应用程序做出的各种断言。所有可用的断言都记录在下面的列表中：

assertTitleassertTitleContainsassertUrlIsassertSchemeIsassertSchemeIsNotassertHostIsassertHostIsNotassertPortIsassertPortIsNotassertPathBeginsWithassertPathEndsWithassertPathContainsassertPathIsassertPathIsNotassertRouteIsassertQueryStringHasassertQueryStringMissingassertFragmentIsassertFragmentBeginsWithassertFragmentIsNotassertHasCookieassertHasPlainCookieassertCookieMissingassertPlainCookieMissingassertCookieValueassertPlainCookieValueassertSeeassertDontSeeassertSeeInassertDontSeeInassertSeeAnythingInassertSeeNothingInassertCountassertScriptassertSourceHasassertSourceMissingassertSeeLinkassertDontSeeLinkassertInputValueassertInputValueIsNotassertCheckedassertNotCheckedassertIndeterminateassertRadioSelectedassertRadioNotSelectedassertSelectedassertNotSelectedassertSelectHasOptionsassertSelectMissingOptionsassertSelectHasOptionassertSelectMissingOptionassertValueassertValueIsNotassertAttributeassertAttributeMissingassertAttributeContainsassertAttributeDoesntContainassertAriaAttributeassertDataAttributeassertVisibleassertPresentassertNotPresentassertMissingassertInputPresentassertInputMissingassertDialogOpenedassertEnabledassertDisabledassertButtonEnabledassertButtonDisabledassertFocusedassertNotFocusedassertAuthenticatedassertGuestassertAuthenticatedAsassertVueassertVueIsNotassertVueContainsassertVueDoesntContain

断言标题 ​

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

php
$browser->assertTitle($title);

断言标题包含 ​

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

php
$browser->assertTitleContains($title);

断言 URL ​

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

php
$browser->assertUrlIs($url);

断言方案 ​

断言当前 URL 方案与给定方案匹配：

php
$browser->assertSchemeIs($scheme);

断言方案不存在 ​

断言当前 URL 方案与给定方案不匹配：

php
$browser->assertSchemeIsNot($scheme);

断言主机Is ​

断言当前 URL 主机与给定主机匹配：

php
$browser->assertHostIs($host);

断言主机不存在 ​

断言当前 URL 主机与给定主机不匹配：

php
$browser->assertHostIsNot($host);

断言端口 ​

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

php
$browser->assertPortIs($port);

断言端口不存在 ​

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

php
$browser->assertPortIsNot($port);

断言路径开始于 ​

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

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

断言路径结束方式 ​

断言当前 URL 路径以给定路径结尾：

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

断言路径包含 ​

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

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

断言路径Is ​

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

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

断言路径不存在 ​

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

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

断言路由Is ​

断言当前 URL 与给定的 named route's URL 匹配：

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

断言查询字符串有 ​

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

php
$browser->assertQueryStringHas($name);

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

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

断言查询字符串缺失 ​

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

php
$browser->assertQueryStringMissing($name);

断言片段Is ​

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

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

断言片段开始于 ​

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

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

断言片段不存在 ​

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

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

断言参见 ​

断言页面上存在给定文本：

php
$browser->assertSee($text);

断言看不到 ​

断言页面上不存在给定文本：

php
$browser->assertDontSee($text);

断言查看 ​

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

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

断言看不到 ​

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

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

断言查看任何内容 ​

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

php
$browser->assertSeeAnythingIn($selector);

断言SeeNothingIn ​

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

php
$browser->assertSeeNothingIn($selector);

断言计数 ​

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

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

断言脚本 ​

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

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

断言源有 ​

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

php
$browser->assertSourceHas($code);

断言源缺失 ​

断言页面上不存在给定的源代码：

php
$browser->assertSourceMissing($code);

断言页面上存在给定的链接：

php
$browser->assertSeeLink($linkText);

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

php
$browser->assertDontSeeLink($linkText);

断言输入值 ​

断言给定的输入字段具有给定的值：

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

断言输入值不是 ​

断言给定的输入字段没有给定的值：

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

断言检查 ​

断言给定的复选框被选中：

php
$browser->assertChecked($field);

断言未检查 ​

断言给定的复选框未被选中：

php
$browser->assertNotChecked($field);

断言不确定 ​

断言给定的复选框处于不确定状态：

php
$browser->assertIndeterminate($field);

断言RadioSelected ​

断言选择了给定的无线电字段：

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

断言RadioNotSelected ​

断言未选择给定的无线电字段：

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

断言选定 ​

断言给定的下拉列表已选择给定值：

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

断言未选择 ​

断言给定的下拉列表没有选择给定的值：

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

断言选择有选项 ​

断言给定的值数组可供选择：

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

断言选择缺失选项 ​

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

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

断言选择有选项 ​

断言可以在给定字段上选择给定值：

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

断言选择缺失选项 ​

断言给定值不可选择：

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

断言值 ​

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

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

断言值不是 ​

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

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

断言属性 ​

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

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

断言属性缺失 ​

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

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

断言属性包含 ​

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

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

断言属性不包含 ​

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

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

断言Aria属性 ​

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

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

例如，给定标记 <button aria-label="Add"></button>，你可以针对 aria-label 属性进行断言，如下所示：

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

断言数据属性 ​

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

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

例如，给定标记 <tr id="row-1" data-content="attendees"></tr>，你可以针对 data-label 属性进行断言，如下所示：

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

断言可见 ​

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

php
$browser->assertVisible($selector);

断言当前 ​

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

php
$browser->assertPresent($selector);

断言不存在 ​

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

php
$browser->assertNotPresent($selector);

断言缺失 ​

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

php
$browser->assertMissing($selector);

断言输入存在 ​

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

php
$browser->assertInputPresent($name);

断言输入缺失 ​

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

php
$browser->assertInputMissing($name);

断言对话框已打开 ​

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

php
$browser->assertDialogOpened($message);

断言启用 ​

断言给定字段已启用：

php
$browser->assertEnabled($field);

断言禁用 ​

断言给定字段已禁用：

php
$browser->assertDisabled($field);

断言按钮已启用 ​

断言给定的按钮已启用：

php
$browser->assertButtonEnabled($button);

断言按钮禁用 ​

断言给定的按钮被禁用：

php
$browser->assertButtonDisabled($button);

断言焦点 ​

断言给定的字段是焦点：

php
$browser->assertFocused($field);

断言未聚焦 ​

断言给定字段没有聚焦：

php
$browser->assertNotFocused($field);

断言已验证 ​

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

php
$browser->assertAuthenticated();

断言来宾 ​

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

php
$browser->assertGuest();

断言AuthenticatedAs ​

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

php
$browser->assertAuthenticatedAs($user);

断言Vue ​

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

// HTML...

<配置文件Dusk=「配置文件组件」></配置文件>

// 组件定义...

Vue.component('个人资料', { 模板：'

{{用户名 }}
',

数据：函数（）{ 返回{ 用户：{ 姓名：「泰勒」 } }; } });

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

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

断言VueIsNot ​

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

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

断言Vue包含 ​

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

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

断言Vue不包含 ​

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

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

页数 ​

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

生成页面 ​

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

shell
php artisan dusk:page Login

配置页面 ​

默认情况下，页面具有三种方法：url、assert 和 elements。我们现在将讨论 url 和 assert 方法。 elements 方法将为 discussed in more detail below。

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 选择器定义快速、易于记住的快捷方式。例如，让我们为应用程序登录页面的「电子邮件」输入字段定义一个快捷方式：

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 后，基础 Page 类将放置在你的 tests/Browser/Pages 目录中。此类包含一个 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 的「页面对象」，但适用于在整个应用程序中重复使用的 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);
            });
    }
}

使用组件 ​

定义组件后，我们可以轻松地从任何测试的日期选择器中选择日期。而且，如果选择日期所需的逻辑发生变化，我们只需要更新组件：

php
<?php

use Illuminate\Foundation\Testing\DatabaseMigrations;
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 应用程序使用端口 8000 上的内置 PHP 开发服务器提供服务。因此，在继续之前，你应该确保你的持续集成环境的 APP_URL 环境变量值为 http://127.0.0.1:8000。

Heroku CI ​

要在 Heroku CI 上运行 Dusk 测试，请将以下 Google Chrome 构建包和脚本添加到你的 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 上运行 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 操作 ​

如果你使用 GitHub Actions 运行 Dusk 测试，你可以使用以下配置文件作为起点。与 TravisCI 一样，我们将使用 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

奇珀 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

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

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

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

要了解有关在 Chipper CI 上运行 Dusk 测试的更多信息，包括如何使用数据库，请参阅 official Chipper CI documentation。