[ Laravel 5.4 文档 ] 测试 —— 浏览器测试(Laravel Dusk)

1、简介

Laravel Dusk 提供了优雅的、易于使用的浏览器自动测试 API。默认情况下,Dusk 不强制你在机器上安装 JDK 或 Selenium,取而代之地,Dusk 基于独立安装的 ChromeDriver。不过,你可以使用任意其他兼容 Selenium 的驱动。

2、安装

开始之前,需要添加 Composer 依赖 laravel/dusk 到项目:

composer require laravel/dusk

安装完 Dusk 后,需要注册服务提供者 Laravel\Dusk\DuskServiceProvider,不过,你需要在 AppServiceProviderregister 方法中注册该提供者,因为它提供了让其他用户登录的权限,以便限制 Dusk 的有效环境:

use Laravel\Dusk\DuskServiceProvider;

/**
 * 注册应用服务.
 *
 * @return void
 */
public function register()
{
    if ($this->app->environment('local', 'testing')) {
        $this->app->register(DuskServiceProvider::class);
    }
}

接下来,运行 Artisan 命令 dusk:install

php artisan dusk:install

运行完该命令后,会在 tests 目录下新建一个 Browser 目录并包含一个测试示例。接下来,在 .env 文件中设置环境变量 APP_URL,该变量值需要和你在浏览器中用于访问应用的URL相匹配。

要运行测试,使用 Artisan 命令 duskdusk 命令接收任意 phpunit 支持的参数:

php artisan dusk

使用其它浏览器

默认情况下,Dusk 使用 Google Chrome 和独立安装的 ChromeDriver 来运行浏览器测试,不过,你也可以启动自己的 Selenium 服务器并在浏览器中进行测试。

开始之前,打开 tests/DuskTestCase.php 文件,该文件是应用的 Dusk 测试用例基类。 在该文件中,你可以移除对 startChromeDriver 方法的调用,这样,就可以阻止 Dusk 自动启动 ChromeDriver:

/**
 * Prepare for Dusk test execution.
 *
 * @beforeClass
 * @return void
 */
public static function prepare()
{
    // static::startChromeDriver();
}

接下来,可以简单编辑 driver 方法连接到你所选择的URL和接口,此外,你可以编辑需要传递给 WebDriver 的“所需功能”:

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

3、快速入门

生成测试

要生成一个 Dusk 测试,使用 Artisan 命令 dusk:make,生成的测试位于 tests/Browser 目录:

php artisan dusk:make LoginTest

运行测试

要运行浏览器测试,使用 Artisan 命令 dusk

php artisan dusk

dusk 命令接收任意 PHPUnit 支持的参数,所以你可以为给定 group 运行测试:

php artisan dusk --group=foo

手动启动ChromeDriver

默认情况下,Dusk 会自动尝试启动 ChromeDriver,如果在你的系统上不生效,你可以在运行 dusk 命令前手动启动 ChromeDriver。如果你选择了手动启动 ChromeDriver,则需要注释掉 tests/DuskTestCase.php 文件中的如下这行代码:

/**
 * Prepare for Dusk test execution.
 *
 * @beforeClass
 * @return void
 */
public static function prepare()
{
    // static::startChromeDriver();
}

此外,如果你不是在 9515 端口上启动ChromeDriver,如果在同一个类中编辑 driver 方法:

/**
 * Create the RemoteWebDriver instance.
 *
 * @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 Tests\DuskTestCase;
use Laravel\Dusk\Chrome;
use Illuminate\Foundation\Testing\DatabaseMigrations;

class ExampleTest extends DuskTestCase
{
    use DatabaseMigrations;

    /**
     * A basic browser test example.
     *
     * @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', 'secret')
                    ->press('Login')
                    ->assertPathIs('/home');
        });
    }
}

正如你在上面示例中所看到的,browse 方法接收一个回调,浏览器实例会通过 Dusk 被自动传递给这个回调并且作为主要对象和应用进行交互并生成断言

注:该测试可用于测试通过 Artisan 命令 make:auth 生成的登录页面。

创建多个浏览器

有时候你需要多个浏览器以便完成测试,例如,在测试与web套接字进行交互的聊天室页面时就需要多个浏览器。要创建多个浏览器,只需在调用 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');
});

认证

我们经常会测试需要认证的页面,可以使用 Dusk 的 loginAs 方法用于避免在每个测试中与登录页面进行交互,loginAs 方法接收用户ID或用户模型实例:

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

4、与元素交互

点击链接

要点击链接,可以使用浏览器实例上的 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 提供了多个方法与表单和输入元素进行交互,首先,让我们看一个输入文本到一个输入字段的例子:

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

注意,尽管 type 方法在需要的时候可以接收,但是我们不实必须要传递 CSS 选择器到该方法。如果没有提供 CSS 选择器,Dusk 会搜索包含给定 name 属性的输入字段,最后,Dusk 会尝试查找包含给定 name 属性的 textarea

你可以使用 clear 方法“清除”输入的值:

$browser->clear('email');

下拉框

要在下拉选择框中选择值,可以使用 select 方法。和 type 方法一样,select 方法不需要完整的 CSS 选择器,当传递值到 select 方法时,需要传递底层 option 值而不是显示文本:

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

你可以通过省略第二个参数来选择一个随机的option:

$browser->select('size');

复选框

要“选择”复选字段,可以使用 check 方法,和其它输入相关方法一样,不需要穿入完整的 CSS 选择器,如果找不到精准匹配的选择器,Dusk 会通过 name 属性搜索响应的复选框:

$browser->check('terms');

$browser->uncheck('terms');

单选按钮

要“选择”一个单选按钮选项,可以使用 radio 方法,和其它输入相关方法一样,不需要完整的 CSS 选择器,如果找不到精准匹配的选择器,Dusk 会搜索匹配 namevalue 属性的单选框:

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

附加文件

attach 方法可用于附加文件到 file 输入元素,和其它输入相关方法一样,也不需要完整的 CSS 选择器,如果精准匹配的选择器找不到,Dusk 会通过 name 属性搜索匹配的文件输入:

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

使用键盘

keys 方法允许你提供比 type 方法更多的复杂输入序列到给定元素。例如,你可以存放编辑键及对应输入值,在本例中,shift键会被存放而taylor被输入到与给定选择器匹配的元素中。输入taylor后,otwell会以不带任何编辑键的形式被输入:

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

你甚至还可以发送“热键”到包含应用的主CSS选择器上:

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

注:所有编辑键都被包裹在 {} 中,并匹配定义在 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);

选择器作用域

有时候你可能只想要在某个给定选择器上执行一系列操作,例如,你可能想要在某个表格中断言文本是否存在然后在同一个表格中点击按钮。你可以使用 with 方法来完成这一功能,传递给 with 方法的回调中所有被执行的操作都被限制在给定的选择器中:

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

等待元素

当测试到广泛使用 JavaScript 的应用时,经常需要等待特定元素或数据加载完成之后才能进行测试。Dusk 让这种测试变得简单,通过使用多种方法,你可以在页面上等待元素变得可访问,甚至直到给定 JavaScript 表达式值为 true

等待

如果你需要暂停测试指定毫秒数,可以使用 pause 方法:

$browser->pause(1000);

等待选择器

waitFor 方法可用于暂停测试执行直到匹配给定 CSS 选择器的元素在页面上显示。默认情况下,这将会在抛出异常前暂停测试最多5秒,如果需要的话,你可以传递自定义超时时间作为该方法的第二个参数:

// 最多等待选择器5s...
$browser->waitFor('.selector');

// 最多等待选择器1s...
$browser->waitFor('.selector', 1);

选择器作用域(有效的话)

某些情况下,你可能想要等待给定选择器然后和匹配给定选择器的元素进行交互。例如,你可能想要等待直到模态窗口有效然后在该窗口中按下“OK”按钮。whenAvailable 方法可以用于此种案例。给定回调中的所有元素操作执行都会限制在特定选择器中:

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

等待文本

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

// 最多等待文本5s...
$browser->waitForText('Hello World');

// 最多等待文本1s...
$browser->waitForText('Hello World', 1);

等待链接

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

// 最多等待链接5s...
$browser->waitForLink('Create');

// 最多等待链接1s...
$browser->waitForLink('Create', 1);

等待JavaScript表达式

有时候你可能想要暂定测试直到JavaScript表达式值为true。你可以简单通过 waitUntil 方法完成这一功能。当暂停表达式时,不需要包含 return 关键词或者结束分号:

// Wait a maximum of five seconds for the expression to be true...
$browser->waitUntil('App.dataLoaded');

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

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

5、有效的断言

Dusk 提供了多种断言用于应用测试,所有有效的断言罗列如下:

断言 描述
$browser->assertTitle($title) 断言页面标题匹配给定文本
$browser->assertTitleContains($title) 断言页面标题包含给定文本
$browser->assertPathIs('/home') 断言当前路径匹配给定路径
$browser->assertQueryStringHas($name, $value) 断言给定查询字符串参数存在并包含给定值
$browser->assertQueryStringMissing($name) 断言给定查询字符串参数缺失
$browser->assertHasCookie($name) 断言给定cookie存在
$browser->assertCookieValue($name, $value) 断言cookie包含给定值
$browser->assertPlainCookieValue($name, $value) 断言未加密cookie包含给定值
$browser->assertSee($text) 断言给定文本在页面存在
$browser->assertDontSee($text) 断言给定文本在页面不存在
$browser->assertSeeIn($selector, $text) 断言给定文本在指定选择器中存在
$browser->assertDontSeeIn($selector, $text) 断言给定文本在指定选择器中不存在
$browser->assertSeeLink($linkText) 断言给定链接在页面中存在
$browser->assertDontSeeLink($linkText) 断言给定链接在页面中不存在
$browser->assertInputValue($field, $value) 断言给定输入字段包含给定值
$browser->assertInputValueIsNot($field, $value) 断言给定输入字段不包含给定值
$browser->assertChecked($field) 断言给定复选框被选中
$browser->assertNotChecked($field) 断言给定复选框未被选中
$browser->assertRadioSelected($field, $value) 断言给定单选框被选中
$browser->assertRadioNotSelected($field, $value) 断言给定单选框未被选中
$browser->assertSelected($field, $value) 断言给定下拉框包含给定选择值
$browser->assertNotSelected($field, $value) 断言给定下拉框不包含给定选择值
$browser->assertValue($selector, $value) 断言匹配给定选择器的元素包含给定值
$browser->assertVisible($selector) 断言匹配给定选择器的元素可以访问
$browser->assertMissing($selector) 断言匹配给定选择器的元素不可以访问

6、页面

有时候,测试需要多个复杂动作在一个序列中执行,这会使得测试代码难以阅读和理解。页面允许你使用单个方法定义优雅的可以在给定页面执行的动作,页面还允许你定义指向应用或单个页面的通用选择器的快捷方式。

生成页面

要生成页面对象,使用 Artisan 命令 dusk:page 即可。所有页面对象都位于 tests/Browser/Pages 目录:

php artisan dusk:page Login

配置页面

默认情况下,页面有三个方法:urlassertelements,下面我们来讨论 urlassert,至于 elements,我们将会在后续选择器速记中详细讨论。

url方法

url 方法会返回代表页面的 URL 路径,Dusk 会在浏览器中导航到页面时使用这个 URL:

/**
 * Get the URL for the page.
 *
 * @return string
 */
public function url()
{
    return '/login';
}

assert方法

assert 方法会生成必要的断言来验证浏览器确实在给定页面,完成这个方法不是必须的;不过,你可以在需要的时候生成这些断言。这些断言将会在导航到页面时自动运行:

/**
 * Assert that the browser is on the page.
 *
 * @return void
 */
public function assert(Browser $browser)
{
    $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 选择器定义快速的、易记的快捷方式,例如,让我们为应用登录页面的“email”输入定义一个快捷方式:

/**
 * Get the element shortcuts for the page.
 *
 * @return array
 */
public function elements()
{
    return [
        '@email' => 'input[name=email]',
    ];
}

现在,你可以在任意你想要试用完整CSS选择器的地方使用速记选择器:

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

全局速记选择器

安装完 Dusk 后,一个基本的 Page 类会生成到 tests/Browser/Pages 目录下。该类包含一个可用于定义全局速记选择器的 siteElement 方法,所谓全局速记选择器,指的是在整个应用中生效的速记选择器:

/**
 * Get the global element shortcuts for the site.
 *
 * @return array
 */
public static function siteElements()
{
    return [
        '@element' => '#selector',
    ];
}

页面方法

除了页面定义的默认方法外,你还可以定义额外的方法用于测试。例如,假设我们正在构建一个音乐管理应用,应用页面常用的功能就是创建一个播放列表,我们不必在每次测试的时候重复编写创建播放列表的逻辑,只需在页面类中定义一个 createPlaylist 方法即可:

<?php

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

class Dashboard extends Page
{
    // Other page methods...

    /**
     * Create a new playlist.
     *
     * @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');
    }
}

定义好方法后,可以在任意使用该页面的测试中使用,浏览器实例会自动传递给页面方法:

use Tests\Browser\Pages\Dashboard;

$browser->visit(new Dashboard)
        ->createPlaylist('My Playlist')
        ->assertSee('My Playlist');

7、继续集成

Travis CI

要在 Travis 上运行 Dusk 测试,需要使用 sudo 权限,由于 Travis CI 并不是一个图形化的环境,我们还需要一些额外的操作步骤以便浏览 Chrome 浏览器。此外,我们将会使用 php artisan serve 来浏览 PHP 的内置 Web 服务器:

sudo: required
dist: trusty

before_script:
    - export DISPLAY=:99.0
    - sh -e /etc/init.d/xvfb start
    - ./vendor/laravel/dusk/bin/chromedriver-linux &
    - cp .env.testing .env
    - php artisan serve &

script:
    - php artisan dusk

Circle CI

如果你在使用 Circle CI 运行 Dusk 测试,可以使用这个配置文件作为起点,和 Travis CI 一样,我们使用 php artisan serve 命令浏览 PHP 的内置服务器:

test:
    pre:
        - "./vendor/laravel/dusk/bin/chromedriver-linux":
            background: true
        - cp .env.testing .env
        - "php artisan serve":
            background: true

    override:
        - php artisan dusk

学院君 has written 716 articles

资深PHP工程师,Laravel学院院长

One thought on “[ Laravel 5.4 文档 ] 测试 —— 浏览器测试(Laravel Dusk)

  1. dominator88 says:

    1) Tests\Browser\ExampleTest::testBasicExample
    Facebook\WebDriver\Exception\WebDriverCurlException: Curl error thrown for http POST to /session with params: {“desiredCapabilities”:{“browserName”:”chrome”,”platform”:”ANY”,”chromeOptions”:{“binary”:””,”args”:[“–disable-gpu”,”–headless”]}}}

    Failed to receive SOCKS5 connect request ack.

    报错了

发表评论

标记为*的字段是必填项(邮箱地址不会被公开)

你可以使用这些HTML 标签和属性: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>