【laravel7.x中文文档】Dusk 浏览器测试

Laravel Dusk

[TOC]

介绍

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。你可以直接用这个方法去等待一个回调函数返回 truewaitUsing 方法接收一个最大的等待秒数,闭包执行的内部时间,闭包,以及一个可选的失败信息:

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

【【laravel7.x中文文档】Dusk 浏览器测试隶属于分类: php laravel

它起初由本站用户:刘欣Eden于4年前 创建。

它被收录于如下合集: Laravel7中文文档

该内容的链接是:

目录