Lzh on GitHub

引言

Pest 4 现在包含自动化浏览器测试，与 Laravel Dusk 相比，它提供了显著的性能和可用性改进。对于新项目，我们建议使用 Pest 进行浏览器测试。

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

安装

要开始，您应该安装 Google Chrome 并将 laravel/dusk Composer 依赖项添加到您的项目中：

composer require laravel/dusk --dev
如果您手动注册 Dusk 的服务提供者，您永远不应在生产环境中注册它，因为这样做可能会导致任意用户能够通过您的应用程序进行身份验证。

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

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 的“期望能力”（desired capabilities）：

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 Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
 
class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;
 
    //
}
在执行 Dusk 测试时不能使用 SQLite 内存数据库。由于浏览器在其自己的进程中执行，它将无法访问其他进程的内存数据库。

使用数据库截断

DatabaseTruncation trait 将在第一次测试时迁移您的数据库，以确保您的数据库表已正确创建。但是，在随后的测试中，数据库的表将被简单地截断——提供了比重新运行所有数据库迁移更快的速度：

<?php

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

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

//

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

如果您使用的是 Pest，您应该在基础 DuskTestCase 类或您的测试文件扩展的任何类上定义属性或方法。
/**
 * 指示应截断哪些表。
 *
 * @var array
 */
protected $tablesToTruncate = ['users'];

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

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

要指定应截断其表的数据库连接，您可以在测试类上定义一个 $connectionsToTruncate 属性：

/**
 * 指示应截断其表的连接。
 *
 * @var array
 */
protected $connectionsToTruncate = ['mysql'];

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

/**
 * 在数据库开始截断之前执行任何工作。
 */
protected function beforeTruncatingDatabase(): void
{
    //
}
 
/**
 * 在数据库截断完成之后执行任何工作。
 */
protected function afterTruncatingDatabase(): void
{
    //
}

运行测试

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

php artisan dusk

如果您上次运行 dusk 命令时测试失败，您可以通过使用 dusk:fails 命令首先重新运行失败的测试来节省时间：

php artisan dusk:fails

dusk 命令接受 Pest / PHPUnit 测试运行器通常接受的任何参数，例如只运行给定 组 的测试：

php artisan dusk --group=foo
如果您正在使用 Laravel Sail 来管理您的本地开发环境，请查阅 Sail 文档中关于 配置和运行 Dusk 测试 的内容。

手动启动 ChromeDriver

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

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

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

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

环境处理

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

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

浏览器基础

创建浏览器

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

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

正如您在上面的示例中看到的，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($routeName, $parameters);

您可以使用 back 和 forward 方法“后退”和“前进”：

$browser->back();
 
$browser->forward();

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

$browser->refresh();

调整浏览器窗口大小

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

$browser->resize(1920, 1080);

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

$browser->maximize();

fitContent 方法将调整浏览器窗口大小以匹配其内容的大小：

$browser->fitContent();

当测试失败时，Dusk 将在截图之前自动调整浏览器以适应内容。您可以通过在测试中调用 disableFitOnFailure 方法来禁用此功能：

$browser->disableFitOnFailure();

您可以使用 move 方法将浏览器窗口移动到屏幕上的不同位置：

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

浏览器宏

如果您想定义一个可以在各种测试中重复使用的自定义浏览器方法，您可以使用 Browser 类上的 macro 方法。通常，您应该从服务提供者的 boot 方法中调用此方法：

<?php
 
namespace App\Providers;
 
use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Browser;
 
class DuskServiceProvider extends ServiceProvider
{
    /**
     * 注册 Dusk 的浏览器宏。
     */
    public function boot(): void
    {
        Browser::macro('scrollToElement', function (string $element = null) {
            $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");
 
            return $this;
        });
    }
}

macro 函数接受一个名称作为其第一个参数，一个闭包作为其第二个参数。当在 Browser 实例上作为方法调用宏时，宏的闭包将被执行：

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

认证

通常，您会测试需要认证的页面。您可以使用 Dusk 的 loginAs 方法，以避免在每次测试期间与应用程序的登录屏幕交互。loginAs 方法接受与您的可认证模型关联的主键或可认证模型实例：

use App\Models\User;
use Laravel\Dusk\Browser;
 
$this->browse(function (Browser $browser) {
    $browser->loginAs(User::find(1))
        ->visit('/home');
});
使用 loginAs 方法后，用户会话将在文件中的所有测试中保持。

Cookies

您可以使用 cookie 方法获取或设置加密 cookie 的值。默认情况下，Laravel 创建的所有 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');

screenshotElement 方法可用于截取页面上特定元素的截图：

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

将控制台输出存储到磁盘

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

$browser->storeConsoleLog('filename');

将页面源代码存储到磁盘

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

$browser->storeSource('filename');

与元素交互

Dusk 选择器

为与元素交互选择好的 CSS 选择器是编写 Dusk 测试最困难的部分之一。随着时间的推移，前端更改可能会导致像下面这样的 CSS 选择器破坏您的测试：

<button>Login</button>

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

Dusk 选择器让您可以专注于编写有效的测试，而不是记住 CSS 选择器。要定义一个选择器，请向您的 HTML 元素添加一个 dusk 属性。然后，当与 Dusk 浏览器交互时，在选择器前加上 @ 来在测试中操作附加的元素：

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

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

如果需要，您可以通过 selectorHtmlAttribute 方法自定义 Dusk 选择器使用的 HTML 属性。通常，此方法应从应用程序 AppServiceProvider 的 boot 方法中调用：

use Laravel\Dusk\Dusk;
 
Dusk::selectorHtmlAttribute('data-dusk');

文本、值和属性

检索和设置值

Dusk 提供了几种方法来与页面上元素的当前值、显示文本和属性进行交互。例如，要获取与给定 CSS 或 Dusk 选择器匹配的元素的“值”，请使用 value 方法：

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

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

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

检索文本

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

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

检索属性

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

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

与表单交互

输入值

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

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

请注意，虽然该方法在必要时接受一个 CSS 选择器，但我们不需要将其传递给 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 元素上可用的值，您可以使用 select 方法。与 type 方法一样，select 方法不需要完整的 CSS 选择器。将值传递给 select 方法时，您应该传递底层选项值而不是显示文本：

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

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

$browser->select('size');

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

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

复选框

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

$browser->check('terms');

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

$browser->uncheck('terms');

单选按钮

要“选择”一个 radio 输入选项，您可以使用 radio 方法。与许多其他与输入相关的方法一样，不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项，Dusk 将搜索具有匹配 name 和 value 属性的 radio 输入：

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

附加文件

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

$browser->attach('photo', __DIR__.'/photos/mountains.png');
attach 函数要求您的服务器上安装并启用了 Zip PHP 扩展。

按下按钮

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

$browser->press('Login');

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

// 按下按钮并最多等待 5 秒钟使其被启用...
$browser->pressAndWaitFor('Save');
 
// 按下按钮并最多等待 1 秒钟使其被启用...
$browser->pressAndWaitFor('Save', 1);

点击链接

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

$browser->clickLink($linkText);

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

if ($browser->seeLink($linkText)) {
    // ...
}
这些方法与 jQuery 交互。如果页面上没有 jQuery，Dusk 将自动将其注入页面，以便在测试期间可用。

使用键盘

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

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

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

$browser->keys('.app', ['{command}', 'j']);
所有修饰键，例如 {command}，都用 {} 字符包裹，并与 Facebook\WebDriver\WebDriverKeys 类中定义的常量匹配，该常量可以 在 GitHub 上 找到。

流畅的键盘交互

Dusk 还提供了一个 withKeyboard 方法，允许您通过 Laravel\Dusk\Keyboard 类流畅地执行复杂的键盘交互。Keyboard 类提供了 press、release、type 和 pause 方法：

use Laravel\Dusk\Keyboard;
 
$browser->withKeyboard(function (Keyboard $keyboard) {
    $keyboard->press('c')
        ->pause(1000)
        ->release('c')
        ->type(['c', 'e', 'o']);
});

键盘宏

如果您想定义可以在整个测试套件中轻松重复使用的自定义键盘交互，您可以使用 Keyboard 类提供的 macro 方法。通常，您应该从服务提供者的 boot 方法中调用此方法：

<?php
 
namespace App\Providers;
 
use Facebook\WebDriver\WebDriverKeys;
use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Keyboard;
use Laravel\Dusk\OperatingSystem;
 
class DuskServiceProvider extends ServiceProvider
{
    /**
     * 注册 Dusk 的浏览器宏。
     */
    public function boot(): void
    {
        Keyboard::macro('copy', function (string $element = null) {
            $this->type([
                OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'c',
            ]);
 
            return $this;
        });
 
        Keyboard::macro('paste', function (string $element = null) {
            $this->type([
                OperatingSystem::onMac() ? WebDriverKeys::META : WebDriverKeys::CONTROL, 'v',
            ]);
 
            return $this;
        });
    }
}

macro 函数接受一个名称作为其第一个参数，一个闭包作为其第二个参数。当在 Keyboard 实例上作为方法调用宏时，宏的闭包将被执行：

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

使用鼠标

点击元素

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

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

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

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

clickAtPoint 方法可用于点击在浏览器可见区域内给定坐标处的最顶层元素：

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

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

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

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

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

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

$browser->clickAndHold('.selector');
 
$browser->clickAndHold()
    ->pause(1000)
    ->releaseMouse();

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

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

鼠标悬停

当您需要将鼠标移动到与给定 CSS 或 Dusk 选择器匹配的元素上时，可以使用 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');

如果 JavaScript 对话框包含提示，您可以使用 typeInDialog 方法在提示中输入值：

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

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

$browser->acceptDialog();

要通过单击“取消”按钮关闭打开的 JavaScript 对话框，您可以调用 dismissDialog 方法：

$browser->dismissDialog();

与内联框架交互

如果您需要与 iframe 中的元素交互，您可以使用 withinFrame 方法。在提供给 withinFrame 方法的闭包中发生的所有元素交互都将作用域限定在指定的 iframe 上下文中：

$browser->withinFrame('#credit-card-details', function ($browser) {
    $browser->type('input[name="cardnumber"]', '4242424242424242')
        ->type('input[name="exp-date"]', '1224')
        ->type('input[name="cvc"]', '123')
        ->press('Pay');
});

限定选择器范围

有时您可能希望在将所有操作限定在给定选择器范围内时执行多个操作。例如，您可能希望断言某些文本仅存在于表格中，然后单击该表格中的按钮。您可以使用 with 方法来实现此目的。在提供给 with 方法的闭包中执行的所有操作都将作用域限定在原始选择器上：

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

您有时可能需要在当前作用域之外执行断言。您可以使用 elsewhere 和 elsewhereWhenAvailable 方法来实现此目的：

$browser->with('.table', function (Browser $table) {
    // 当前作用域是 `body .table`...
 
    $browser->elsewhere('.page-title', function (Browser $title) {
        // 当前作用域是 `body .page-title`...
        $title->assertSee('Hello World');
    });
 
    $browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
        // 当前作用域是 `body .page-title`...
        $title->assertSee('Hello World');
    });
});

等待元素

在测试大量使用 JavaScript 的应用程序时，在继续测试之前“等待”某些元素或数据可用通常是必要的。Dusk 使这变得轻而易举。使用各种方法，您可以等待元素在页面上变得可见，甚至等待给定的 JavaScript 表达式评估为 true。

等待

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

$browser->pause(1000);

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

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

同样，如果您需要暂停测试，除非给定条件为 true，否则您可以使用 pauseUnless 方法：

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

等待选择器

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

// 最多等待五秒钟来等待选择器...
$browser->waitFor('.selector');
 
// 最多等待一秒钟来等待选择器...
$browser->waitFor('.selector', 1);

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

// 最多等待五秒钟来等待选择器包含给定文本...
$browser->waitForTextIn('.selector', 'Hello World');
 
// 最多等待一秒钟来等待选择器包含给定文本...
$browser->waitForTextIn('.selector', 'Hello World', 1);

您还可以等到与给定选择器匹配的元素从页面上消失：

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

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

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

可用时限定选择器范围

有时，您可能希望等待出现一个与给定选择器匹配的元素，然后与该元素交互。例如，您可能希望等到一个模态窗口可用，然后按下模态中的“确定”按钮。whenAvailable 方法可用于实现此目的。在给定闭包中执行的所有元素操作都将作用域限定在原始选择器上：

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

等待文本

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

// 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 方法来等待，直到显示的文本已从页面中移除：

// 最多等待五秒钟来等待文本被移除...
$browser->waitUntilMissingText('Hello World');
 
// 最多等待一秒钟来等待文本被移除...
$browser->waitUntilMissingText('Hello World', 1);

等待链接

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

// 最多等待五秒钟来等待链接...
$browser->waitForLink('Create');
 
// 最多等待一秒钟来等待链接...
$browser->waitForLink('Create', 1);

等待输入

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

// 最多等待五秒钟来等待输入...
$browser->waitForInput($field);
 
// 最多等待一秒钟来等待输入...
$browser->waitForInput($field, 1);

等待页面位置

当进行路径断言（例如 $browser->assertPathIs('/home')）时，如果 window.location.pathname 正在异步更新，断言可能会失败。您可以使用 waitForLocation 方法来等待位置成为给定值：

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

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

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

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

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

等待页面重载

如果您需要在执行某个操作后等待页面重载，请使用 waitForReload 方法：

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

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

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

等待 JavaScript 表达式

有时您可能希望暂停测试的执行，直到给定的 JavaScript 表达式评估为 true。您可以使用 waitUntil 方法轻松实现此目的。将表达式传递给此方法时，您不需要包含 return 关键字或结束分号：

// 最多等待五秒钟来等待表达式为 true...
$browser->waitUntil('App.data.servers.length > 0');
 
// 最多等待一秒钟来等待表达式为 true...
$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');
 
// 最多等待五秒钟直到窗口被调整大小...
$browser->waitForEvent('resize', 'window', 5);

带回调的等待

Dusk 中的许多“等待”方法都依赖于底层的 waitUsing 方法。您可以直接使用此方法来等待给定的闭包返回 true。waitUsing 方法接受要等待的最大秒数、应评估闭包的间隔、闭包以及一个可选的失败消息：

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

将元素滚动到视图中

有时，您可能无法点击某个元素，因为它位于浏览器的可视区域之外。scrollIntoView 方法将滚动浏览器窗口，直到给定选择器处的元素位于视图中：

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

可用断言

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

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

$browser->assertTitle($title);

assertTitleContains

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

$browser->assertTitleContains($title);

assertUrlIs

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

$browser->assertUrlIs($url);

assertSchemeIs

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

$browser->assertSchemeIs($scheme);

assertSchemeIsNot

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

$browser->assertSchemeIsNot($scheme);

assertHostIs

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

$browser->assertHostIs($host);

assertHostIsNot

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

$browser->assertHostIsNot($host);

assertPortIs

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

$browser->assertPortIs($port);

assertPortIsNot

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

$browser->assertPortIsNot($port);

assertPathBeginsWith

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

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

assertPathEndsWith

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

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

assertPathContains

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

$browser->assertPathContains('/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');

assertHasCookie

断言给定的加密 cookie 存在：

$browser->assertHasCookie($name);

assertHasPlainCookie

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

$browser->assertHasPlainCookie($name);

assertCookieMissing

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

$browser->assertCookieMissing($name);

assertPlainCookieMissing

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

$browser->assertPlainCookieMissing($name);

assertCookieValue

断言加密 cookie 具有给定值：

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

assertPlainCookieValue

断言未加密 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);

assertSeeNothingIn

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

$browser->assertSeeNothingIn($selector);

assertCount

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

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

assertScript

断言给定的 JavaScript 表达式评估为给定值：

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

assertSourceHas

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

$browser->assertSourceHas($code);

assertSourceMissing

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

$browser->assertSourceMissing($code);

assertSeeLink

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

$browser->assertSeeLink($linkText);

assertDontSeeLink

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

$browser->assertDontSeeLink($linkText);

assertInputValue

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

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

assertInputValueIsNot

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

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

assertChecked

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

$browser->assertChecked($field);

assertNotChecked

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

$browser->assertNotChecked($field);

assertIndeterminate

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

$browser->assertIndeterminate($field);

assertRadioSelected

断言给定的单选字段被选中：

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

assertRadioNotSelected

断言给定的单选字段未被选中：

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

assertSelected

断言给定的下拉菜单具有给定值被选中：

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

assertNotSelected

断言给定的下拉菜单没有给定的值被选中：

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

assertAttributeMissing

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

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

assertAttributeContains

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

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

assertAttributeDoesntContain

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

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

assertAriaAttribute

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

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

例如，给定标记 <button aria-label="Add"></button>，您可以像这样对 aria-label 属性进行断言：

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

assertDataAttribute

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

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

<profile dusk="profile-component"></profile>
 
Vue.component('profile', {
    template: '<div>{{ user.name }}</div>',
 
    data: function () {
        return {
            user: {
                name: 'Taylor'
            }
        };
    }
});

您可以像这样对 Vue 组件的状态进行断言：

test('vue', function () {
    $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);

assertVueDoesntContain

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

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

页面

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

生成页面

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

php artisan dusk:page Login

配置页面

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

url 方法

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

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

assert 方法

assert 方法可以进行任何必要的断言，以验证浏览器是否确实在给定页面上。实际上，在此方法中放置任何东西都不是必需的；但是，如果您愿意，可以自由地进行这些断言。当导航到该页面时，这些断言将自动运行：

/**
 * 断言浏览器在该页面上。
 */
public function assert(Browser $browser): void
{
    $browser->assertPathIs($this->url());
}

导航到页面

一旦定义了页面，您就可以使用 visit 方法导航到它：

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

有时您可能已经在给定页面上，需要将页面的选择器和方法“加载”到当前的测试上下文中。当按下按钮并被重定向到给定页面而没有明确导航到它时，这很常见。在这种情况下，您可以使用 on 方法加载页面：

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

速记选择器

页面类中的 elements 方法允许您为页面上的任何 CSS 选择器定义快速、易于记忆的快捷方式。例如，让我们为应用程序登录页面的“电子邮件”输入字段定义一个快捷方式：

/**
 * 获取页面的元素快捷方式。
 *
 * @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;
use Laravel\Dusk\Page;
 
class Dashboard extends Page
{
    // 其他页面方法...
 
    /**
     * 创建一个新的播放列表。
     */
    public function createPlaylist(Browser $browser, string $name): void
    {
        $browser->type('name', $name)
            ->check('share')
            ->press('Create Playlist');
    }
}

一旦定义了方法，您就可以在任何使用该页面的测试中使用它。浏览器实例将自动作为第一个参数传递给自定义页面方法：

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

组件

组件类似于 Dusk 的“页面对象”，但它们旨在用于在您的应用程序中重复使用的 UI 和功能片段，例如导航栏或通知窗口。因此，组件不与特定的 URL 绑定。

生成组件

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

php artisan dusk:component DatePicker

如上所示，“日期选择器”是可能在您的应用程序的各种页面上存在的组件的一个示例。在整个测试套件的数十个测试中手动编写浏览器自动化逻辑来选择日期可能会很麻烦。相反，我们可以定义一个 Dusk 组件来表示日期选择器，从而允许我们将该逻辑封装在组件中：

<?php
 
namespace Tests\Browser\Components;
 
use Laravel\Dusk\Browser;
use Laravel\Dusk\Component as BaseComponent;
 
class DatePicker extends BaseComponent
{
    /**
     * 获取组件的根选择器。
     */
    public function selector(): string
    {
        return '.date-picker';
    }
 
    /**
     * 断言浏览器页面包含组件。
     */
    public function assert(Browser $browser): void
    {
        $browser->assertVisible($this->selector());
    }
 
    /**
     * 获取组件的元素快捷方式。
     *
     * @return array<string, string>
     */
    public function elements(): array
    {
        return [
            '@date-field' => 'input.datepicker-input',
            '@year-list' => 'div > div.datepicker-years',
            '@month-list' => 'div > div.datepicker-months',
            '@day-list' => 'div > div.datepicker-days',
        ];
    }
 
    /**
     * 选择给定的日期。
     */
    public function selectDate(Browser $browser, int $year, int $month, int $day): void
    {
        $browser->click('@date-field')
            ->within('@year-list', function (Browser $browser) use ($year) {
                $browser->click($year);
            })
            ->within('@month-list', function (Browser $browser) use ($month) {
                $browser->click($month);
            })
            ->within('@day-list', function (Browser $browser) use ($day) {
                $browser->click($day);
            });
    }
}

使用组件

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

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

component 方法可用于检索作用域限定在给定组件的浏览器实例：

$datePicker = $browser->component(new DatePickerComponent);
 
$datePicker->selectDate(2019, 1, 30);
 
$datePicker->assertSee('January');

持续集成

大多数 Dusk 持续集成配置都期望您的 Laravel 应用程序使用内置的 PHP 开发服务器在端口 8000 上提供服务。因此，在继续之前，您应该确保您的持续集成环境的 APP_URL 环境变量值为 http://127.0.0.1:8000。

Heroku CI

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

{
  "environments": {
    "test": {
      "buildpacks": [
        { "url": "heroku/php" },
        { "url": "https://github.com/heroku/heroku-buildpack-chrome-for-testing" }
      ],
      "scripts": {
        "test-setup": "cp .env.testing .env",
        "test": "nohup bash -c './vendor/laravel/dusk/bin/chromedriver-linux --port=9515 > /dev/null 2>&1 &' && nohup bash -c 'php artisan serve --no-reload > /dev/null 2>&1 &' && php artisan dusk"
      }
    }
  }
}

Travis CI

要在 Travis CI 上运行您的 Dusk 测试，请使用以下 .travis.yml 配置。由于 Travis CI 不是一个图形环境，我们需要采取一些额外的步骤来启动 Chrome 浏览器。此外，我们将使用 php artisan serve 来启动 PHP 的内置 Web 服务器：

language: php
 
php:
  - 8.2
 
addons:
  chrome: stable
 
install:
  - cp .env.testing .env
  - travis_retry composer install --no-interaction --prefer-dist
  - php artisan key:generate
  - php artisan dusk:chrome-driver
 
before_script:
  - google-chrome-stable --headless --disable-gpu --remote-debugging-port=9222 http://localhost &
  - php artisan serve --no-reload &
 
script:
  - php artisan dusk

GitHub Actions

如果您正在使用 GitHub Actions 来运行您的 Dusk 测试，您可以使用以下配置文件作为起点。与 TravisCI 一样，我们将使用 php artisan serve 命令来启动 PHP 的内置 Web 服务器：

name: CI
on: [push]
jobs:
 
  dusk-php:
    runs-on: ubuntu-latest
    env:
      APP_URL: "http://127.0.0.1:8000"
      DB_USERNAME: root
      DB_PASSWORD: root
      MAIL_MAILER: log
    steps:
      - uses: actions/checkout@v4
      - name: Prepare The Environment
        run: cp .env.example .env
      - name: Create Database
        run: |
          sudo systemctl start mysql
          mysql --user="root" --password="root" -e "CREATE DATABASE \`my-database\` character set UTF8mb4 collate utf8mb4_bin;"
      - name: Install Composer Dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader
      - name: Generate Application Key
        run: php artisan key:generate
      - name: Upgrade Chrome Driver
        run: php artisan dusk:chrome-driver --detect
      - name: Start Chrome Driver
        run: ./vendor/laravel/dusk/bin/chromedriver-linux --port=9515 &
      - name: Run Laravel Server
        run: php artisan serve --no-reload &
      - name: Run Dusk Tests
        run: php artisan dusk
      - name: Upload Screenshots
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: tests/Browser/screenshots
      - name: Upload Console Logs
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: console
          path: tests/Browser/console

Chipper CI

如果您正在使用 Chipper CI 来运行您的 Dusk 测试，您可以使用以下配置文件作为起点。我们将使用 PHP 的内置服务器来运行 Laravel，以便我们可以监听请求：

# file .chipperci.yml
version: 1
 
environment:
  php: 8.2
  node: 16
 
# 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 测试的更多信息，包括如何使用数据库，请查阅 官方的 Chipper CI 文档。