Laravel Dusk

介绍

Laravel Dusk 提供了富有表现力、简单易用的浏览器自动化及测试 API 。默认情况下，Dusk 不需要在你的机器上安装 JDK 或者 Selenium 。而是需要使用单独的 ChromeDriver 进行安装。当然，你也可以自由使用其他的兼容 Selenium 的驱动程序。

安装

你应该先向你的 Composer 添加 laravel/dusk 依赖 ：

composer require --dev laravel/dusk

{note} 如果你是手动注册 Dusk 服务提供者，一定 不能 在你的生产环境中注册，这样可能会导致一些不守规矩的用户拥有控制你应用的权限。

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

php artisan dusk:install

Browser 目录将会在 tests 目录下被创建，并且包含一个测试用例。接下来，在你的 .env 文件中设置 APP_URL 变量。这个值应该与你在浏览器中打开本应用的 URL 匹配。

要运行测试，使用 dusk 命令。 dusk 命令可以使用与 phpunit 命令同样的参数：

php artisan dusk

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

php artisan dusk:fails

管理 ChromeDriver 安装

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

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

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

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

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

使用其他浏览器

默认情况下， Dusk 使用 Google Chrome 浏览器和一个单独的 ChromeDriver 的安装来运行你的浏览器测试。当然，你可以运行你自己的 Selenium 服务，用任何你想用的浏览器来进行测试。

如果要这么做，打开 tests/DuskTestCase.php 文件，这个是应用测试用例的基类。在这个文件中，你可以移除对 startChromeDriver 方法的调用。这样 Dusk 就不会自动启动 ChromeDriver 了。

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

然后，你可以修改 driver 方法来连接到你选定的 URL 和端口。此外，你可以修改 「desired capabilities」（期望能力），它将会被传递给 WebDriver：

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

开始使用

创建测试

要创建一个 Dusk 测试，使用 dusk:make 命令。创建的测试将会被放在 tests/Browser 目录：

php artisan dusk:make LoginTest

运行测试

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

php artisan dusk

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

php artisan dusk:fails

dusk 命令接受任何能让 PHPUnit 正常运行的参数。例如，让你可以在指定 group 中运行测试：

php artisan dusk --group=foo

手动运行 ChromeDriver

默认情况下，Dusk 会尝试自动运行 ChromeDriver。如果你在特定的系统中不能运行，可以在运行 dusk 命令前通过手动的方式来运行 ChromeDriver。 如果你选择手动运行 ChromeDriver，你需要在你的 tests/DuskTestCase.php 文件中注释掉下面这一行：

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

另外，如果你的 ChromeDriver 运行在非 9515 端口 ，你需要修改同一个类中的 driver 方法：

/**
 * 创建 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

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 方法的回调中，用名字来区分浏览器实例，然后传给回调去「申请」多个浏览器实例：

$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 方法去调整浏览器的窗口大小：

$browser->resize(1920, 1080);

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

$browser->maximize();

fitContent 方法将自动适配浏览器的窗口大小和页面内容的尺寸:

$browser->fitContent();

测试失败时，Dusk 会自动将浏览器窗口缩放至内容大小并拍下屏幕快照，你可以通过调用 disableFitOnFailure 方法来禁用这一特性：

$browser->disableFitOnFailure();

浏览器宏

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

<?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 的实现的方法时，浏览器宏的闭包将会执行：

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

认证

你可能经常会测试一些需要认证的页面。你可以使用 Dusk 的 loginAs 方法来避免每个测试都去登陆页面登陆一次。 loginAs 可以使用用户 ID 或者用户模型实例：

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

注意：使用 loginAs 方法后，该用户的 session 将会持久化的供其他测试用例使用。

数据库迁移

就像上面的认证例子一样，当你的测试用例需要迁移的时候，你不应该使用 RefreshDatabase trait。 RefreshDatabase trait 使用了不适用于 HTTP 请求的数据库事务。取而代之，我们要用 DatabaseMigrations trait：

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

与元素交互

Dusk 选择器

选择一个好的 CSS 选择器用于元素交互是编写 Dush 测试最困难的部分之一。随着时间推移，前端的更改可能会导致类似以下的 CSS 选择器中断测试：

// HTML...

<button>Login</button>

// Test...

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

Dusk 选择器让你专注于编写有效的测试，而不是去记忆 CSS 选择器。要定义一个选择器，只需在你的 HTML 元素中添加一个 dusk 属性。然后，在选择器前面添加 @ 去操作 Dusk 测试中的附加元素：

// HTML...

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

// Test...

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

点击链接

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

$browser->clickLink($linkText);

注意：这个方法可以与 jQuery 进行交互。如果页面上没有 jQuery，Dusk 会自动将其注入页面，保证在测试的期间可用。

文本、值和属性

检索和设置值

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

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

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

检索文本

text 这个方法可以用来匹配指定选择器中元素的显示文本：

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

检索属性

最后，attribute 这个方法 可以用来匹配指定选择器中元素的属性：

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

使用表单

输入值

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

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

注意， 虽然 type 方法可以传递 CSS 选择器做为一个参数，但这并不是强制要求的。如果没有提供 CSS 选择器， Dusk 会搜索与 name 属性相同的 input 。如果还是没有找到，Dusk 会尝试查找传入值与 name 属性相同的 textarea 。

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

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

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

$browser->clear('email');

下拉菜单

需要在下拉菜单中选择值，你可以使用 select 方法。 类似于 type 方法， select 方法并不是一定要传入 CSS 选择器。 当使用 select 方法时，你应该传递选项实际的值而不是它的显示文本：

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

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

$browser->select('size');

复选框

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

$browser->check('terms');

$browser->uncheck('terms');

单选按钮

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

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

附件

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

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

{note} attach 方法需要使用 PHP Zip 扩展，你的服务器必须安装了此扩展。

使用键盘

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

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

你甚至可以在你的应用中选中某个元素之后按下「快捷键」：

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

{tip} 所有包在 {} 中的键盘按键， 都对应定义于 Facebook\WebDriver\WebDriverKeys 类中，你可以在 GitHub 中找到。

使用鼠标

点击元素

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

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

鼠标悬停

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

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

拖放

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

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

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

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

JavaScript 对话框

Dusk 提供了几种与 JavaScript 对话框交互的方法：

// 等待对话框显示：
$browser->waitForDialog($seconds = null);

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

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

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

$browser->acceptDialog();

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

$browser->dismissDialog();

选择器作用范围

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

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

等待元素

在测试大面积使用 JavaScript 的应用时，在进行测试之前，经常需要「等待」指定元素或数据可用。Dusk 使之更容易。使用一系列方法，可以等到页面元素可用，甚至给定的 JavaScript 表达式执行结果为 true。

等待

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

$browser->pause(1000);

等待选择器

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

// 等待选择器 5 秒时间...
$browser->waitFor('.selector');

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

还可以等待指定选择器从页面消失：

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

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

选择器可用时限定作用域范围

偶尔可能希望等待选择器然后与其互动。例如，可能希望等待模态窗口可用，然后点击模态窗口的「确定」按钮。 whenAvailable 方法能够用于这种情况。给定回调内的所有要执行的元素操作都将被限定在起始选择器上：

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

等待文本

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

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

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

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

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

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

等待链接

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

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

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

等待页面跳转

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

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

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

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

等待页面重新加载

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

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

等待 JavaScript 表达式

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

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

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

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

等待 Vue 表达式

下述方法可用于一直等待，直到一个给定的 Vue 组件属性有特定的值：

// 一直等待，直到组件属性有特定的值
$browser->waitUntilVue('user.name', 'Taylor', '@user');

// 一直等待，直到组件不包含给定的值
$browser->waitUntilVueIsNot('user.name', null, '@user');

使用回调函数来等待

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

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

创建 Vue 断言

Dusk 甚至还允许你对 Vue 组件数据的状态进行断言。比如：假设你的应用有如下的 Vue 组件：

// HTML...

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

// 组件的定义

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

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

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

/**
 * A basic Vue test example.
 *
 * @return void
 */
public function testVue()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/')
                ->assertVue('user.name', 'Taylor', '@profile-component');
    });
}