Laravel 7.x 中文文档

简体中文

English

简体中文

English

主题

Laravel Dusk ​

介绍 ​

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

安装 ​

要开始使用，你应该将 laravel/dusk Composer 依赖添加到你的项目中：

php
composer require --dev laravel/dusk
exclamation

如果你手动注册 Dusk 的服务提供者，你绝不应该在生产环境中注册它，因为这样做可能会导致任意用户能够与您的应用程序进行身份验证。

安装 Dusk 包后，运行 dusk:install Artisan 命令：

php
php artisan dusk:install

一个 Browser 目录将会在你的 tests 目录中创建，并包含一个示例测试。接下来，在你的 .env 文件中设置 APP_URL 环境变量。这个值应该与您在浏览器中访问应用程序时使用的 URL 匹配。

要运行你的测试，使用 dusk Artisan 命令。dusk 命令接受任何 phpunit 命令也接受的参数：

php
php artisan dusk

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

php
php artisan dusk:fails

管理 ChromeDriver 安装 ​

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

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

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

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

Dusk 需要 chromedriver 二进制文件是可执行的。如果你在运行 Dusk 时遇到问题，你应该确保二进制文件是可执行的，使用以下命令：chmod -R 0755 vendor/laravel/dusk/bin/。

使用其他浏览器 ​

默认情况下，Dusk 使用 Google Chrome 和一个独立的 ChromeDriver 安装来运行你的浏览器测试。然而，你可以启动自己的 Selenium 服务器并在任何你希望的浏览器上运行你的测试。

要开始，打开你的 tests/DuskTestCase.php 文件，这是你的应用程序的基本 Dusk 测试用例。在这个文件中，你可以删除对 startChromeDriver 方法的调用。这将阻止 Dusk 自动启动 ChromeDriver：

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

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

php
/**
 * 创建 RemoteWebDriver 实例。
 *
 * @return \Facebook\WebDriver\Remote\RemoteWebDriver
 */
protected function driver()
{
    return RemoteWebDriver::create(
        'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
    );
}

入门 ​

生成测试 ​

要生成一个 Dusk 测试，使用 dusk:make Artisan 命令。生成的测试将被放置在 tests/Browser 目录中：

php
php artisan dusk:make LoginTest

运行测试 ​

要运行你的浏览器测试，使用 dusk Artisan 命令：

php
php artisan dusk

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

php
php artisan dusk:fails

dusk 命令接受任何通常由 PHPUnit 测试运行器接受的参数，允许你仅运行给定 组 的测试，等等：

php
php artisan dusk --group=foo

手动启动 ChromeDriver ​

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

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

此外，如果你在 9515 以外的端口上启动 ChromeDriver，你应该修改同一类的 driver 方法：

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

环境处理 ​

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

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

创建浏览器 ​

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

php
<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    /**
     * 一个基本的浏览器测试示例。
     *
     * @return void
     */
    public function testBasicExample()
    {
        $user = factory(User::class)->create([
            'email' => 'taylor@laravel.com',
        ]);

        $this->browse(function ($browser) use ($user) {
            $browser->visit('/login')
                    ->type('email', $user->email)
                    ->type('password', 'password')
                    ->press('Login')
                    ->assertPathIs('/home');
        });
    }
}

如上例所示，browse 方法接受一个回调。Dusk 将自动将一个浏览器实例传递给这个回调，并且是用于与应用程序交互和进行断言的主要对象。

创建多个浏览器 ​

有时你可能需要多个浏览器才能正确执行测试。例如，可能需要多个浏览器来测试与 websockets 交互的聊天屏幕。要创建多个浏览器，请在传递给 browse 方法的回调的签名中“请求”多个浏览器：

php
$this->browse(function ($first, $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');
});

调整浏览器窗口大小 ​

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

php
$browser->resize(1920, 1080);

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

php
$browser->maximize();

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

php
$browser->fitContent();

当测试失败时，Dusk 将自动调整浏览器的大小以适应内容，然后再截取屏幕截图。你可以通过在测试中调用 disableFitOnFailure 方法来禁用此功能：

php
$browser->disableFitOnFailure();

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

php
$browser->move(100, 100);

浏览器宏 ​

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

php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Browser;

class DuskServiceProvider extends ServiceProvider
{
    /**
     * 注册 Dusk 的浏览器宏。
     *
     * @return void
     */
    public function boot()
    {
        Browser::macro('scrollToElement', function ($element = null) {
            $this->script("$('html, body').animate({ scrollTop: $('$element').offset().top }, 0);");

            return $this;
        });
    }
}

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

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

认证 ​

通常，你将测试需要认证的页面。你可以使用 Dusk 的 loginAs 方法来避免在每个测试中与登录屏幕交互。loginAs 方法接受一个用户 ID 或用户模型实例：

php
$this->browse(function ($first, $second) {
    $first->loginAs(User::find(1))
          ->visit('/home');
});
exclamation

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

数据库迁移 ​

当你的测试需要迁移时，如上面的认证示例，你不应该使用 RefreshDatabase trait。RefreshDatabase trait 利用数据库事务，这在 HTTP 请求中将不适用。相反，使用 DatabaseMigrations trait：

php
<?php

namespace Tests\Browser;

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

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;
}

Cookies ​

你可以使用 cookie 方法获取或设置加密 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');

截屏 ​

你可以使用 screenshot 方法截取屏幕截图并使用给定的文件名存储它。所有屏幕截图将存储在 tests/Browser/screenshots 目录中：

php
$browser->screenshot('filename');

将控制台输出存储到磁盘 ​

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

php
$browser->storeConsoleLog('filename');

将页面源代码存储到磁盘 ​

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

php
$browser->storeSource('filename');

与元素交互 ​

Dusk 选择器 ​

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

php
// HTML...

<button>Login</button>

// 测试...

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

Dusk 选择器允许你专注于编写有效的测试，而不是记住 CSS 选择器。要定义选择器，请在 HTML 元素中添加一个 dusk 属性。然后，在 Dusk 测试中使用 @ 前缀选择器来操作附加的元素：

php
// HTML...

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

// 测试...

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

点击链接 ​

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

php
$browser->clickLink($linkText);

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

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

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

文本、值和属性 ​

检索和设置值 ​

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

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

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

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

php
// 检索输入元素的值...
$inputValue = $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 属性的输入字段。最后，Dusk 将尝试找到具有给定 name 属性的 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 方法。与 type 方法一样，select 方法不需要完整的 CSS 选择器。在将值传递给 select 方法时，你应该传递底层选项值而不是显示文本：

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

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

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

复选框 ​

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

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

$browser->uncheck('terms');

单选按钮 ​

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

php
$browser->radio('version', 'php7');

附加文件 ​

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

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

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

使用键盘 ​

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

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

你甚至可以将“热键”发送到包含你的应用程序的主要 CSS 选择器：

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

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

使用鼠标 ​

点击元素 ​

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

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

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

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

clickAtPoint 方法可用于“点击”浏览器可视区域内给定坐标处的最上层元素：

php
$browser->clickAtPoint(0, 0);

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

php
$browser->doubleClick();

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

php
$browser->rightClick();

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

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

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

鼠标悬停 ​

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

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

拖放 ​

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

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

或者，你可以将元素拖动到单个方向：

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

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

php
$browser->dragOffset('.selector', 10, 10);

JavaScript 对话框 ​

Dusk 提供了多种方法来与 JavaScript 对话框进行交互：

php
// 等待对话框出现：
$browser->waitForDialog($seconds = null);

// 断言对话框已显示并且其消息与给定值匹配：
$browser->assertDialogOpened('value');

// 在打开的 JavaScript 提示对话框中输入给定值：
$browser->typeInDialog('Hello World');

要关闭打开的 JavaScript 对话框，点击 OK 按钮：

php
$browser->acceptDialog();

要关闭打开的 JavaScript 对话框，点击 Cancel 按钮（仅适用于确认对话框）：

php
$browser->dismissDialog();

选择器范围 ​

有时你可能希望在给定选择器内执行多个操作。例如，你可能希望断言某些文本仅存在于表格中，然后点击该表格中的按钮。你可以使用 with 方法来实现这一点。在传递给 with 方法的回调中执行的所有操作都将限定在原始选择器内：

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

你可能偶尔需要在当前范围之外执行断言。你可以使用 elsewhere 方法来实现这一点：

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

等待元素 ​

在测试大量使用 JavaScript 的应用程序时，通常需要“等待”某些元素或数据可用，然后再继续测试。Dusk 使这变得很简单。使用多种方法，你可以等待页面上的元素可见，甚至可以等待给定的 JavaScript 表达式计算为 true。

等待 ​

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

php
$browser->pause(1000);

等待选择器 ​

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

php
// 最多等待五秒钟以获取选择器...
$browser->waitFor('.selector');

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

你还可以等待给定选择器从页面中消失：

php
$browser->waitUntilMissing('.selector');

$browser->waitUntilMissing('.selector', 1);

在可用时限定选择器 ​

有时，你可能希望等待给定选择器，然后与匹配该选择器的元素进行交互。例如，你可能希望等待一个模态窗口可用，然后按下模态中的“OK”按钮。在这种情况下，可以使用 whenAvailable 方法。在传递给 whenAvailable 方法的回调中执行的所有元素操作都将限定在原始选择器内：

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

等待文本 ​

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

php
// 最多等待五秒钟以获取文本...
$browser->waitForText('Hello World');

// 最多等待一秒钟以获取文本...
$browser->waitForText('Hello World', 1);

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

php
// 最多等待五秒钟以删除文本...
$browser->waitUntilMissingText('Hello World');

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

等待链接 ​

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

php
// 最多等待五秒钟以获取链接...
$browser->waitForLink('Create');

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

等待页面位置 ​

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

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

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

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

等待页面重新加载 ​

如果你需要在页面重新加载后进行断言，请使用 waitForReload 方法：

php
$browser->click('.some-action')
        ->waitForReload()
        ->assertSee('something');

等待 JavaScript 表达式 ​

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

php
// 最多等待五秒钟以使表达式为 true...
$browser->waitUntil('App.dataLoaded');

$browser->waitUntil('App.data.servers.length > 0');

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

等待 Vue 表达式 ​

以下方法可用于等待给定的 Vue 组件属性具有给定值：

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

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

使用回调等待 ​

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

进行 Vue 断言 ​

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

php
// HTML...

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

// 组件定义...

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

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

你可以对 Vue 组件的状态进行如下断言：

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

可用断言 ​

Dusk 提供了多种断言，你可以对你的应用程序进行断言。所有可用的断言都在下面的列表中记录：

assertTitleassertTitleContainsassertUrlIsassertSchemeIsassertSchemeIsNotassertHostIsassertHostIsNotassertPortIsassertPortIsNotassertPathBeginsWithassertPathIsassertPathIsNotassertRouteIsassertQueryStringHasassertQueryStringMissingassertFragmentIsassertFragmentBeginsWithassertFragmentIsNotassertHasCookieassertHasPlainCookieassertCookieMissingassertPlainCookieMissingassertCookieValueassertPlainCookieValueassertSeeassertDontSeeassertSeeInassertDontSeeInassertSourceHasassertSourceMissingassertSeeLinkassertDontSeeLinkassertInputValueassertInputValueIsNotassertCheckedassertNotCheckedassertRadioSelectedassertRadioNotSelectedassertSelectedassertNotSelectedassertSelectHasOptionsassertSelectMissingOptionassertSelectMissingOptionsassertSelectHasOptionassertValueassertAttributeassertAriaAttributeassertDataAttributeassertVisibleassertPresentassertMissingassertDialogOpenedassertEnabledassertDisabledassertButtonEnabledassertButtonDisabledassertFocusedassertNotFocusedassertAuthenticatedassertGuestassertAuthenticatedAsassertVueassertVueIsNotassertVueContainsassertVueDoesNotContain

assertTitle ​

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

php
$browser->assertTitle($title);

assertTitleContains ​

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

php
$browser->assertTitleContains($title);

assertUrlIs ​

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

php
$browser->assertUrlIs($url);

assertSchemeIs ​

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

php
$browser->assertSchemeIs($scheme);

assertSchemeIsNot ​

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

php
$browser->assertSchemeIsNot($scheme);

assertHostIs ​

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

php
$browser->assertHostIs($host);

assertHostIsNot ​

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

php
$browser->assertHostIsNot($host);

assertPortIs ​

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

php
$browser->assertPortIs($port);

assertPortIsNot ​

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

php
$browser->assertPortIsNot($port);

assertPathBeginsWith ​

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

php
$browser->assertPathBeginsWith($path);

assertPathIs ​

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

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

assertPathIsNot ​

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

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

assertRouteIs ​

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

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

assertQueryStringHas ​

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

php
$browser->assertQueryStringHas($name);

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

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

assertQueryStringMissing ​

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

php
$browser->assertQueryStringMissing($name);

assertFragmentIs ​

断言当前片段与给定片段匹配：

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

assertFragmentBeginsWith ​

断言当前片段以给定片段开头：

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

assertFragmentIsNot ​

断言当前片段不与给定片段匹配：

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

assertHasCookie ​

断言给定加密 cookie 存在：

php
$browser->assertHasCookie($name);

assertHasPlainCookie ​

断言给定未加密 cookie 存在：

php
$browser->assertHasPlainCookie($name);

assertCookieMissing ​

断言给定加密 cookie 不存在：

php
$browser->assertCookieMissing($name);

assertPlainCookieMissing ​

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

php
$browser->assertPlainCookieMissing($name);

assertCookieValue ​

断言加密 cookie 具有给定值：

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

assertPlainCookieValue ​

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

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

assertSee ​

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

php
$browser->assertSee($text);

assertDontSee ​

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

php
$browser->assertDontSee($text);

assertSeeIn ​

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

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

assertDontSeeIn ​

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

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

assertSourceHas ​

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

php
$browser->assertSourceHas($code);

assertSourceMissing ​

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

php
$browser->assertSourceMissing($code);

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

php
$browser->assertSeeLink($linkText);

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

php
$browser->assertDontSeeLink($linkText);

assertInputValue ​

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

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

assertInputValueIsNot ​

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

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

assertChecked ​

断言给定复选框已选中：

php
$browser->assertChecked($field);

assertNotChecked ​

断言给定复选框未选中：

php
$browser->assertNotChecked($field);

assertRadioSelected ​

断言给定单选字段已选中：

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

assertRadioNotSelected ​

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

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

assertSelected ​

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

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

assertNotSelected ​

断言给定的下拉框未选择给定的值：

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

assertSelectHasOptions ​

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

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

assertSelectMissingOption ​

断言给定的值不可供选择：

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

assertSelectMissingOptions ​

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

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

assertSelectHasOption ​

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

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

assertValue ​

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

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

assertAttribute ​

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

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

assertAriaAttribute ​

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

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

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

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

assertDataAttribute ​

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

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

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

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

assertVisible ​

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

php
$browser->assertVisible($selector);

assertPresent ​

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

php
$browser->assertPresent($selector);

assertMissing ​

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

php
$browser->assertMissing($selector);

assertDialogOpened ​

断言打开了具有给定消息的JavaScript对话框：

php
$browser->assertDialogOpened($message);

assertEnabled ​

断言给定字段是启用的：

php
$browser->assertEnabled($field);

assertDisabled ​

断言给定字段是禁用的：

php
$browser->assertDisabled($field);

assertButtonEnabled ​

断言给定按钮是启用的：

php
$browser->assertButtonEnabled($button);

assertButtonDisabled ​

断言给定按钮是禁用的：

php
$browser->assertButtonDisabled($button);

assertFocused ​

断言给定字段是聚焦的：

php
$browser->assertFocused($field);

assertNotFocused ​

断言给定字段未聚焦：

php
$browser->assertNotFocused($field);

assertAuthenticated ​

断言用户已认证：

php
$browser->assertAuthenticated();

assertGuest ​

断言用户未认证：

php
$browser->assertGuest();

assertAuthenticatedAs ​

断言用户已认证为给定用户：

php
$browser->assertAuthenticatedAs($user);

assertVue ​

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

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

assertVueIsNot ​

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

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

assertVueContains ​

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

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

assertVueDoesNotContain ​

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

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

页面 ​

有时，测试需要按顺序执行几个复杂的操作。这可能会使您的测试难以阅读和理解。页面允许您定义可以在给定页面上使用单个方法执行的表达性操作。页面还允许您为应用程序或单个页面定义常用选择器的快捷方式。

生成页面 ​

要生成页面对象，请使用 dusk:page Artisan 命令。所有页面对象将放置在 tests/Browser/Pages 目录中：

php
php artisan dusk:page Login

配置页面 ​

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

url 方法 ​

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

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

assert 方法 ​

assert 方法可以进行任何必要的断言，以验证浏览器实际上在给定页面上。完成此方法不是必需的；但是，如果您愿意，可以进行这些断言。这些断言将在导航到页面时自动运行：

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

导航到页面 ​

配置页面后，您可以使用 visit 方法导航到它：

php
use Tests\Browser\Pages\Login;

$browser->visit(new Login);

您可以使用 visitRoute 方法导航到命名路由：

php
$browser->visitRoute('login');

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

php
$browser->back();

$browser->forward();

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

php
$browser->refresh();

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

php
use Tests\Browser\Pages\CreatePlaylist;

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

简写选择器 ​

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

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

现在，您可以在任何使用完整CSS选择器的地方使用此简写选择器：

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

全局简写选择器 ​

安装Dusk后，一个基础 Page 类将放置在您的 tests/Browser/Pages 目录中。此类包含一个 siteElements 方法，可用于定义在整个应用程序的每个页面上都应可用的全局简写选择器：

php
/**
 * 获取站点的全局元素快捷方式。
 *
 * @return array
 */
public static function siteElements()
{
    return [
        '@element' => '#selector',
    ];
}

页面方法 ​

除了页面上定义的默认方法外，您还可以定义其他方法，这些方法可以在您的测试中使用。例如，假设我们正在构建一个音乐管理应用程序。应用程序的一个页面的常见操作可能是创建播放列表。您可以在页面类上定义一个 createPlaylist 方法，而不是在每个测试中重写创建播放列表的逻辑：

php
<?php

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class Dashboard extends Page
{
    // 其他页面方法...

    /**
     * 创建一个新播放列表。
     *
     * @param  \Laravel\Dusk\Browser  $browser
     * @param  string  $name
     * @return void
     */
    public function createPlaylist(Browser $browser, $name)
    {
        $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 目录中：

php
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
{
    /**
     * 获取组件的根选择器。
     *
     * @return string
     */
    public function selector()
    {
        return '.date-picker';
    }

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

    /**
     * 获取组件的元素快捷方式。
     *
     * @return array
     */
    public function elements()
    {
        return [
            '@date-field' => 'input.datepicker-input',
            '@year-list' => 'div > div.datepicker-years',
            '@month-list' => 'div > div.datepicker-months',
            '@day-list' => 'div > div.datepicker-days',
        ];
    }

    /**
     * 选择给定日期。
     *
     * @param  \Laravel\Dusk\Browser  $browser
     * @param  int  $year
     * @param  int  $month
     * @param  int  $day
     * @return void
     */
    public function selectDate($browser, $year, $month, $day)
    {
        $browser->click('@date-field')
                ->within('@year-list', function ($browser) use ($year) {
                    $browser->click($year);
                })
                ->within('@month-list', function ($browser) use ($month) {
                    $browser->click($month);
                })
                ->within('@day-list', function ($browser) use ($day) {
                    $browser->click($day);
                });
    }
}

使用组件 ​

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

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
{
    /**
     * 一个基本的组件测试示例。
     *
     * @return void
     */
    public function testBasicExample()
    {
        $this->browse(function (Browser $browser) {
            $browser->visit('/')
                    ->within(new DatePicker, function ($browser) {
                        $browser->selectDate(2019, 1, 30);
                    })
                    ->assertSee('January');
        });
    }
}

持续集成 ​

exclamation

在添加持续集成配置文件之前，请确保您的 .env.testing 文件包含一个 APP_URL 条目，其值为 http://127.0.0.1:8000。

CircleCI ​

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

php
version: 2
jobs:
    build:
        steps:
            - run: sudo apt-get install -y libsqlite3-dev
            - run: cp .env.testing .env
            - run: composer install -n --ignore-platform-reqs
            - run: php artisan key:generate
            - run: php artisan dusk:chrome-driver
            - run: npm install
            - run: npm run production
            - run: vendor/bin/phpunit

            - run:
                name: Start Chrome Driver
                command: ./vendor/laravel/dusk/bin/chromedriver-linux
                background: true

            - run:
                name: Run Laravel Server
                command: php artisan serve
                background: true

            - run:
                name: Run Laravel Dusk Tests
                command: php artisan dusk

            - store_artifacts:
                path: tests/Browser/screenshots

            - store_artifacts:
                path: tests/Browser/console

            - store_artifacts:
                path: storage/logs

Codeship ​

要在 Codeship 上运行Dusk测试，请将以下命令添加到您的Codeship项目中。这些命令只是一个起点，您可以根据需要添加其他命令：

php
phpenv local 7.2
cp .env.testing .env
mkdir -p ./bootstrap/cache
composer install --no-interaction --prefer-dist
php artisan key:generate
php artisan dusk:chrome-driver
nohup bash -c "php artisan serve 2>&1 &" && sleep 5
php artisan dusk

Heroku CI ​

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

php
{
  "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 > /dev/null 2>&1 &' && php artisan dusk"
      }
    }
  }
}

Travis CI ​

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

php
language: php

php:
  - 7.3

addons:
  chrome: stable

install:
  - cp .env.testing .env
  - travis_retry composer install --no-interaction --prefer-dist --no-suggest
  - 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 &

script:
  - php artisan dusk

GitHub Actions ​

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

php
name: CI
on: [push]
jobs:

  dusk-php:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - 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 --no-suggest --prefer-dist --optimize-autoloader
      - name: Generate Application Key
        run: php artisan key:generate
      - name: Upgrade Chrome Driver
        run: php artisan dusk:chrome-driver `/opt/google/chrome/chrome --version | cut -d " " -f3 | cut -d "." -f1`
      - name: Start Chrome Driver
        run: ./vendor/laravel/dusk/bin/chromedriver-linux &
      - name: Run Laravel Server
        run: php artisan serve &
      - name: Run Dusk Tests
        env:
          APP_URL: "http://127.0.0.1:8000"
        run: php artisan dusk

版权所有 © 2024-2025 laravel.wiki