Appearance
Laravel Dusk
简介
Laravel Dusk 提供了一个富有表现力、易于使用的浏览器自动化和测试 API。默认情况下,Dusk 不需要你在本地计算机上安装 JDK 或 Selenium。相反,Dusk 使用独立的 ChromeDriver 安装。然而,你可以自由使用任何其他与 Selenium 兼容的驱动程序。
安装
要开始使用,你应该安装 Google Chrome 并将 laravel/dusk
Composer 依赖项添加到你的项目中:
shell
composer require laravel/dusk --dev
WARNING
如果你手动注册 Dusk 的服务提供者,你应该永远不要在生产环境中注册它,因为这样做可能会导致任意用户能够验证你的应用程序。
安装 Dusk 包后,执行 dusk:install
Artisan 命令。dusk:install
命令将创建一个 tests/Browser
目录,一个示例 Dusk 测试,并为你的操作系统安装 Chrome Driver 二进制文件:
shell
php artisan dusk:install
接下来,在应用程序的 .env
文件中设置 APP_URL
环境变量。这个值应该与你在浏览器中访问应用程序时使用的 URL 匹配。
NOTE
如果你正在使用 Laravel Sail 来管理你的本地开发环境,请同时查阅 Sail 文档中关于配置和运行 Dusk 测试的内容。
管理 ChromeDriver 安装
如果你想安装与 Laravel Dusk 通过 dusk:install
命令安装的版本不同的 ChromeDriver 版本,你可以使用 dusk:chrome-driver
命令:
shell
# 为你的操作系统安装最新版本的 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
WARNING
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
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
接下来,你可以修改 driver
方法以连接到你选择的 URL 和端口。此外,你可以修改应该传递给 WebDriver 的"期望能力":
php
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
目录中:
shell
php artisan dusk:make LoginTest
每次测试后重置数据库
你编写的大多数测试都会与从应用程序数据库检索数据的页面进行交互;然而,你的 Dusk 测试不应该使用 RefreshDatabase
trait。RefreshDatabase
trait 利用数据库事务,这在 HTTP 请求之间将不适用或可用。相反,你有两个选择: DatabaseMigrations
trait 和 DatabaseTruncation
trait。
使用数据库迁移
DatabaseMigrations
trait 将在每次测试之前运行你的数据库迁移。然而,为每个测试删除和重新创建数据库表通常比截断表慢:
php
<?php
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(DatabaseMigrations::class);
//
php
<?php
namespace Tests\Browser;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
//
}
WARNING
执行 Dusk 测试时不能使用 SQLite 内存数据库。由于浏览器在自己的进程中执行,它将无法访问其他进程的内存数据库。
使用数据库截断
DatabaseTruncation
trait 将在第一个测试中迁移你的数据库,以确保你的数据库表已正确创建。然而,在后续测试中,数据库的表将简单地被截断 - 这比重新运行所有数据库迁移提供了速度提升:
php
<?php
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
uses(DatabaseTruncation::class);
//
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseTruncation;
//
}
默认情况下,这个 trait 将截断除 migrations
表之外的所有表。如果你想自定义应该被截断的表,你可以在测试类上定义一个 $tablesToTruncate
属性:
NOTE
如果你正在使用 Pest,你应该在基础 DuskTestCase
类或你的测试文件扩展的任何类上定义属性或方法。
php
/**
* 指示应该被截断的表。
*
* @var array
*/
protected $tablesToTruncate = ['users'];
或者,你可以在测试类上定义一个 $exceptTables
属性来指定应该从截断中排除的表:
php
/**
* 指示应该从截断中排除的表。
*
* @var array
*/
protected $exceptTables = ['users'];
要指定应该截断其表的数据库连接,你可以在测试类上定义一个 $connectionsToTruncate
属性:
php
/**
* 指示应该截断其表的连接。
*
* @var array
*/
protected $connectionsToTruncate = ['mysql'];
如果你想在执行数据库截断之前或之后执行代码,你可以在测试类上定义 beforeTruncatingDatabase
或 afterTruncatingDatabase
方法:
php
/**
* 在数据库开始截断之前执行任何工作。
*/
protected function beforeTruncatingDatabase(): void
{
//
}
/**
* 在数据库完成截断后执行任何工作。
*/
protected function afterTruncatingDatabase(): void
{
//
}
运行测试
要运行你的浏览器测试,执行 dusk
Artisan 命令:
shell
php artisan dusk
如果你在上次运行 dusk
命令时有测试失败,你可以通过使用 dusk:fails
命令首先重新运行失败的测试来节省时间:
shell
php artisan dusk:fails
dusk
命令接受 Pest / PHPUnit 测试运行器通常接受的任何参数,例如允许你只运行给定 组 的测试:
shell
php artisan dusk --group=foo
NOTE
如果你正在使用 Laravel Sail 来管理你的本地开发环境,请查阅 Sail 文档中关于配置和运行 Dusk 测试的内容。
手动启动 ChromeDriver
默认情况下,Dusk 会自动尝试启动 ChromeDriver。如果这对你的特定系统不起作用,你可以在运行 dusk
命令之前手动启动 ChromeDriver。如果你选择手动启动 ChromeDriver,你应该注释掉 tests/DuskTestCase.php
文件中的以下行:
php
/**
* 准备 Dusk 测试执行。
*
* @beforeClass
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
此外,如果你在 9515 以外的端口上启动 ChromeDriver,你应该修改同一类的 driver
方法以反映正确的端口:
php
use Facebook\WebDriver\Remote\RemoteWebDriver;
/**
* 创建 RemoteWebDriver 实例。
*/
protected function driver(): RemoteWebDriver
{
return RemoteWebDriver::create(
'http://localhost:9515', DesiredCapabilities::chrome()
);
}
环境处理
运行测试时,Dusk 将备份你的 .env
文件并将你的 Dusk 环境重命名为 .env
。一旦测试完成,你的 .env
文件将被恢复。
浏览器基础
创建浏览器
首先,让我们编写一个测试来验证我们可以登录到我们的应用程序。生成测试后,我们可以修改它以导航到登录页面,输入一些凭据,然后点击"登录"按钮。要创建一个浏览器实例,你可以在 Dusk 测试中调用 browse
方法:
php
<?php
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(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');
});
});
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
/**
* 一个基本的浏览器测试示例。
*/
public function test_basic_example(): void
{
$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
方法的闭包��名中添加更多的浏览器参数:
php
$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:
php
$browser->visit('/login');
你可以使用 visitRoute
方法导航到 命名路由:
php
$browser->visitRoute($routeName, $parameters);
你可以使用 back
和 forward
方法进行"后退"和"前进"导航:
php
$browser->back();
$browser->forward();
你可以使用 refresh
方法刷新页面:
php
$browser->refresh();
调整浏览器窗口大小
你可以使用 resize
方法调整浏览器窗口的大小:
php
$browser->resize(1920, 1080);
maximize
方法可用于最大化浏览器窗口:
php
$browser->maximize();
fitContent
方法将调整浏览器窗口大小以匹配其内容的大小:
php
$browser->fitContent();
当测试失败时,Dusk 会自动调整浏览器大小以适应内容,然后再截图。你可以通过在测试中调用 disableFitOnFailure
方法来禁用此功能:
php
$browser->disableFitOnFailure();
你可以使用 move
方法将浏览器窗口移动到屏幕上的不同位置:
php
$browser->move($x = 100, $y = 100);
浏览器宏
如果你想定义一个可以在各种测试中重复使用的自定义浏览器方法,你可以在 Browser
类上使用 macro
方法。通常,你应该从 服务提供者 的 boot
方法中调用此方法:
php
<?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
实例上调用宏作为方法时,将执行宏的闭包:
php
$this->browse(function (Browser $browser) use ($user) {
$browser->visit('/pay')
->scrollToElement('#credit-card-details')
->assertSee('Enter Credit Card Details');
});
认证
通常,你会测试需要认证的页面。你可以使用 Dusk 的 loginAs
方法来避免在每次测试期间与应用程序的登录屏幕交互。loginAs
方法接受与你的可认证模型关联的主键或可认证模型实例:
php
use App\Models\User;
use Laravel\Dusk\Browser;
$this->browse(function (Browser $browser) {
$browser->loginAs(User::find(1))
->visit('/home');
});
WARNING
使用 loginAs
方法后,用户会话将在文件中的所有测试中保持。
Cookies
你可以使用 cookie
方法获取或设置加密 cookie 的值。默认情况下,Laravel 创建的所有 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');
执行 JavaScript
你可以使用 script
方法在浏览器中执行任意 JavaScript 语句:
php
$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
目录中:
php
$browser->screenshot('filename');
responsiveScreenshots
方法可用于在各种断点处拍摄一系列截图:
php
$browser->responsiveScreenshots('filename');
screenshotElement
方法可用于截取页面上特定元素的截图:
php
$browser->screenshotElement('#selector', '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');
如果需要,你可以通过 selectorHtmlAttribute
方法自定义 Dusk 选择器使用的 HTML 属性。通常,应该在应用程序的 AppServiceProvider
的 boot
方法中调用此方法:
php
use Laravel\Dusk\Dusk;
Dusk::selectorHtmlAttribute('data-dusk');
文本、值和属性
检索和设置值
Dusk 提供了几种方法来与页面上元素的当前值、显示文本和属性进行交互。例如,要获取与给定 CSS 或 Dusk 选择器匹配的元素的"值",使用 value
方法:
php
// 检索值...
$value = $browser->value('selector');
// 设置值...
$browser->value('selector', 'value');
你可以使用 inputValue
方法获取具有给定字段名称的输入元素的"值":
php
$value = $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
属性的 input
或 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');
下拉菜单
php
$browser->select('size', 'Large');
你可以通过省略第二个参数来选择一个随机选项:
php
$browser->select('size');
通过提供一个数组作为 select
方法的第二个参数,你可以指示该方法选择多个选项:
php
$browser->select('categories', ['Art', 'Music']);
复选框
要"选中"一个复选框输入,你可以使用 check
方法。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
属性的复选框:
php
$browser->check('terms');
uncheck
方法可用于"取消选中"复选框输入:
php
$browser->uncheck('terms');
单选按钮
要"选择"一个 radio
输入选项,你可以使用 radio
方法。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
和 value
属性的 radio
输入:
php
$browser->radio('size', 'large');
附加文件
attach
方法可用于将文件附加到 file
输入元素。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
属性的 file
输入:
php
$browser->attach('photo', __DIR__.'/photos/mountains.png');
WARNING
attach 函数需要在你的服务器上安装并启用 Zip
PHP 扩展。
按下按钮
press
方法可用于点击页面上的按钮元素。传递给 press
方法的参数可以是按钮的显示文本或 CSS / Dusk 选择器:
php
$browser->press('Login');
当提交表单时,许多应用程序会在按下后禁用表单的提交按钮,然后在表单提交的 HTTP 请求完成时重新启用按钮。要按下按钮并等待按钮重新启用,你可以使用 pressAndWaitFor
方法:
php
// 按下按钮并最多等待 5 秒钟让它启用...
$browser->pressAndWaitFor('Save');
// 按下按钮并最多等待 1 秒钟让它启用...
$browser->pressAndWaitFor('Save', 1);
点击链接
要点击链接,你可以在浏览器实例上使用 clickLink
方法。clickLink
方法将点击具有给定显示文本的链接:
php
$browser->clickLink($linkText);
你可以使用 seeLink
方法来确定具有给定显示文本的链接是否在页面上可见:
php
if ($browser->seeLink($linkText)) {
// ...
}
WARNING
这些方法与 jQuery 交互。如果页面上没有 jQuery,Dusk 将自动将其注入到页面中,以便在测试期间可用。
使用键盘
keys
方法允许你向给定元素提供比 type
方法通常允许的更复杂的输入序列。例如,你可以指示 Dusk 在输入值时按住修饰键。在这个例子中,当向与给定选择器匹配的元素输入 taylor
时,将按住 shift
键。在输入 taylor
后,swift
将在没有任何修饰键的情况下输入:
php
$browser->keys('selector', ['{shift}', 'taylor'], 'swift');
keys
方法的另一个有价值的用例是向应用程序的主 CSS 选择器发送"键盘快捷键"组合:
php
$browser->keys('.app', ['{command}', 'j']);
NOTE
所有修饰键(如 {command}
)都用 {}
字符包裹,并匹配在 GitHub 上可以找到的 Facebook\WebDriver\WebDriverKeys
类中定义的常量。
流畅的键盘交互
Dusk 还提供了一个 withKeyboard
方法,允许你通过 Laravel\Dusk\Keyboard
类流畅地执行复杂的键盘交互。Keyboard
类提供了 press
、release
、type
和 pause
方法:
php
use Laravel\Dusk\Keyboard;
$browser->withKeyboard(function (Keyboard $keyboard) {
$keyboard->press('c')
->pause(1000)
->release('c')
->type(['c', 'e', 'o']);
});
键盘宏
如果你想定义可以在整个测试套件中轻松重用的自定义键盘交互,你可以使用 Keyboard
类提供的 macro
方法。通常,你应该从 服务提供者 的 boot
方法中调用此方法:
php
<?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
实例上调用宏作为方法时,将执行宏的闭包:
php
$browser->click('@textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->copy())
->click('@another-textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->paste());
使用鼠标
点击元素
click
方法可用于点击与给定 CSS 或 Dusk 选择器匹配的元素:
php
$browser->click('.selector');
clickAtXPath
方法可用于点击与给定 XPath 表达式匹配的元素:
php
$browser->clickAtXPath('//div[@class = "selector"]');
clickAtPoint
方法可用于点击浏览器可视区域内给定坐标对处的最上层元素:
php
$browser->clickAtPoint($x = 0, $y = 0);
doubleClick
方法可用于模拟鼠标的双击:
php
$browser->doubleClick();
$browser->doubleClick('.selector');
rightClick
方法可用于模拟鼠标的右键点击:
php
$browser->rightClick();
$browser->rightClick('.selector');
php
<?php
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(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');
});
});
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
/**
* 一个基本的浏览器测试示例。
*/
public function test_basic_example(): void
{
$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
方法的闭包签名中添加更多的浏览器参数:
php
$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:
php
$browser->visit('/login');
你可以使用 visitRoute
方法导航到 命名路由:
php
$browser->visitRoute($routeName, $parameters);
你可以使用 back
和 forward
方法进行"后退"和"前进"导航:
php
$browser->back();
$browser->forward();
你可以使用 refresh
方法刷新页面:
php
$browser->refresh();
调整浏览器窗口大小
你可以使用 resize
方法调整浏览器窗口的大小:
php
$browser->resize(1920, 1080);
maximize
方法可用于最大化浏览器窗口:
php
$browser->maximize();
fitContent
方法将调整浏览器窗口大小以匹配其内容的大小:
php
$browser->fitContent();
当测试失败时,Dusk 会自动调整浏览器大小以适应内容,然后再截图。你可以通过在测试中调用 disableFitOnFailure
方法来禁用此功能:
php
$browser->disableFitOnFailure();
你可以使用 move
方法将浏览器窗口移动到屏幕上的不同位置:
php
$browser->move($x = 100, $y = 100);
浏览器宏
如果你想定义一个可以在各种测试中重复使用的自定义浏览器方法,你可以在 Browser
类上使用 macro
方法。通常,你应该从 ���务提供者 的 boot
方法中调用此方法:
php
<?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
实例上调用宏作为方法时,将执行宏的闭包:
php
$this->browse(function (Browser $browser) use ($user) {
$browser->visit('/pay')
->scrollToElement('#credit-card-details')
->assertSee('Enter Credit Card Details');
});
认证
通常,你会测试需要认证的页面。你可以使用 Dusk 的 loginAs
方法来避免在每次测试期间与应用程序的登录屏幕交互。loginAs
方法接受与你的可认证模型关联的主键或可认证模型实例:
php
use App\Models\User;
use Laravel\Dusk\Browser;
$this->browse(function (Browser $browser) {
$browser->loginAs(User::find(1))
->visit('/home');
});
WARNING
使用 loginAs
方法后,用户会话将在文件中的所有测试中保持。
Cookies
你可以使用 cookie
方法获取或设置加密 cookie 的值。默认情况下,Laravel 创建的所有 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');
执行 JavaScript
你可以使用 script
方法在浏览器��执行任意 JavaScript ��句:
php
$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
目录中:
php
$browser->screenshot('filename');
responsiveScreenshots
方法可用于在各种断点处拍摄一系列截图:
php
$browser->responsiveScreenshots('filename');
screenshotElement
方法可用于截取页面上特定元素的截图:
php
$browser->screenshotElement('#selector', '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');
如果需要,你可以通过 selectorHtmlAttribute
方法自定义 Dusk 选择器使用的 HTML 属性。通常,应该在应用程序的 AppServiceProvider
的 boot
方法中调用此方法:
php
use Laravel\Dusk\Dusk;
Dusk::selectorHtmlAttribute('data-dusk');
文本、值和属性
检索和设置值
Dusk 提供了几种方法来与页面上元素的当前值、显示文本和属性进行交互。例如,要获取与给定 CSS 或 Dusk 选择器匹配的元素的"值",使用 value
方法:
php
// 检索值...
$value = $browser->value('selector');
// 设置值...
$browser->value('selector', 'value');
你可以使用 inputValue
方法获取具有给定字段名称的输入元素的"值":
php
$value = $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
属性的 input
或 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');
下拉菜单
php
$browser->select('size', 'Large');
你可以通过省略第二个参数来选择一个随机选项:
php
$browser->select('size');
通过提供一个数组作为 select
方法的第二个参数,你可以指示该方法选择多个选项:
php
$browser->select('categories', ['Art', 'Music']);
复选框
要"选中"一个复选框输入,你可以使用 check
方法。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
属性的复选框:
php
$browser->check('terms');
uncheck
方法可用于"取消选中"复选框输入:
php
$browser->uncheck('terms');
单选按钮
要"选择"一个 radio
输入选项,你可以使用 radio
方法。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
和 value
属性的 radio
输入:
php
$browser->radio('size', 'large');
附加文件
attach
方法可用于将文件附加到 file
输入元素。与许多其他输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配,Dusk 将搜索具有匹配 name
属性的 file
输入:
php
$browser->attach('photo', __DIR__.'/photos/mountains.png');
WARNING
attach 函数需要在你的服务器上安装并启用 Zip
PHP 扩展。
按下按钮
press
方法可用于点击页面上的按钮元素。传递给 press
方法的参数可以是按钮的显示文本或 CSS / Dusk 选择器:
php
$browser->press('Login');
当提交表单时,许多应用程序会在按下后禁用表单的提交按钮,然后在表单提交的 HTTP 请求完成时重新启用按钮。要按下按钮并等待按钮重新启用,你可以使用 pressAndWaitFor
方法:
php
// 按下按钮并最多等待 5 秒钟让它启用...
$browser->pressAndWaitFor('Save');
// 按下按钮并最多等待 1 秒钟让它启用...
$browser->pressAndWaitFor('Save', 1);
点击链接
要点击链接,你可以在浏览器实例上使用 clickLink
方法。clickLink
方法将点击具有给定显示文本的链接:
php
$browser->clickLink($linkText);
你可以使用 seeLink
方法来确定具有给定显示文本的链接是否在页面上可见:
php
if ($browser->seeLink($linkText)) {
// ...
}
WARNING
这些方法与 jQuery 交互。如果页面上没有 jQuery,Dusk 将自动将其注入到页面中,以便在测试期间可用。
使用键盘
keys
方法允许你向给定元素提供比 type
方法通常允许的更复杂的输入序列。例如,你可以指示 Dusk 在输入值时按住修饰键。在这个例子中,当向与给定选择器匹配的元素输入 taylor
时,将按住 shift
键。在输入 taylor
后,swift
将在没有任何修饰键的情况下输入:
php
$browser->keys('selector', ['{shift}', 'taylor'], 'swift');
keys
方法的另一个有价值的用例是向应用程序的主 CSS 选择器发送"键盘快捷键"组合:
php
$browser->keys('.app', ['{command}', 'j']);
NOTE
所有修饰键(如 {command}
)都用 {}
字符包裹,并匹配在 GitHub 上可以找到的 Facebook\WebDriver\WebDriverKeys
类中定义的常量。
流畅的键盘交互
Dusk 还提供了一个 withKeyboard
方法,允许你通过 Laravel\Dusk\Keyboard
类流畅地执行复杂的键盘交互。Keyboard
类提供了 press
、release
、type
和 pause
方法:
php
use Laravel\Dusk\Keyboard;
$browser->withKeyboard(function (Keyboard $keyboard) {
$keyboard->press('c')
->pause(1000)
->release('c')
->type(['c', 'e', 'o']);
});
键盘宏
如果你想定义可以在整个测试套件中轻松重用的自定义键盘交互,你可以使用 Keyboard
类提供的 macro
方法。通常,你应该从 服务提供者 的 boot
方法中调用此方法:
php
<?php
namespace App\Providers;
use Facebook\WebDriver\WebDriverKeys;
use Illuminate\Support\ServiceProvider;
use Laravel\Dusk\Keyboard;
```php tab=Pest
<?php
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(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');
});
});
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
/**
* 一个基本的浏览器测试示例。
*/
public function test_basic_example(): void
{
$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
方法的闭包签名中添加更多的浏览器参数:
php
$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:
php
$browser->visit('/login');
你可以使用 visitRoute
方法导航到 命名路由:
php
$browser->visitRoute($routeName, $parameters);
你可以使用 back
和 forward
方法进行"后退"和"前进"导航:
php
$browser->back();
$browser->forward();
你可以使用 refresh
方法刷新页面:
php
$browser->refresh();
调整浏览器窗口大小
你可以使用 resize
方法调整浏览器窗口的大小:
php
$browser->resize(1920, 1080);
maximize
方法可用于最大化浏览器窗口:
php
$browser->maximize();
fitContent
方法将调整浏览器窗口大小以匹配其内容的大小:
php
$browser->fitContent();
当测试失败时,Dusk 会自动调整浏览器大小以适应内容,然后再截图。你可以通过在测试中调用 disableFitOnFailure
方法来禁用此功能:
php
$browser->disableFitOnFailure();
你可以使用 move
方法将浏览器窗口移动到屏幕上的不同位置:
php
$browser->move($x = 100, $y = 100);
浏览器宏
如果你想定义一个可以在各种测试中重复使用的自定义浏览器方法,你可以在 Browser
类上使用 macro
方法。通常,你应该从 服务提供者 的 boot
方法中调用此方法:
php
<?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
实例上调用宏作为方法时,将执行宏的闭包:
php
$this->browse(function (Browser $browser) use ($user) {
$browser->visit('/pay')
->scrollToElement('#credit-card-details')
->assertSee('Enter Credit Card Details');
});
认证
通常,你会测试需要认证的页面。你可以使用 Dusk 的 loginAs
方法来避免在每次测试期间与应用程序的登录屏幕交互。loginAs
方法接受与你的可认证模型关联的主键或可认证模型实例:
php
use App\Models\User;
use Laravel\Dusk\Browser;
$this->browse(function (Browser $browser) {
$browser->loginAs(User::find(1))
->visit('/home');
});
WARNING
使用 loginAs
方法后,用户会话将在文件中的所有测试中保持。
Cookies
你可以使用 cookie
方法获取或设置加密 cookie 的值。默认情况下,Laravel 创建的所有 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');
执行 JavaScript
你可以使用 script
方法在浏览器中执行任意 JavaScript 语句:
php
$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
目录中:
php
$browser->screenshot('filename');
responsiveScreenshots
方法可用于在各种断点处拍摄一系列截图:
php
$browser->responsiveScreenshots('filename');
screenshotElement
方法可用于截取页面上特定元素的截图:
php
$browser->screenshotElement('#selector', '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');
如果需要,你可以通过 selectorHtmlAttribute
方法自定义 Dusk 选择器使用的 HTML 属性。通常,应该在应用程序的 AppServiceProvider
的 boot
方法中调用此方法:
php
use Laravel\Dusk\Dusk;
Dusk::selectorHtmlAttribute('data-dusk');
文本、值和属性
检索和设置值
Dusk 提供了几种方法来与页面上元素的当前值、显示文本和属性进行交互。例如,要获取与给定 CSS 或 Dusk 选择器匹配的元素的"值",使用 value
方法:
php
// 检索值...
$value = $browser->value('selector');
// 设置值...
$browser->value('selector', 'value');
你可以使用 inputValue
方法获取具有给定字段名称的输入元素的"值":
php
$value = $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
属性的 input
或 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');
下拉菜单
php
$browser->select('size', 'Large');
你可以通过省略第二个参数来选择一个随机选项:
php
$browser->select('size');
通过提供一个数组作为 select
方法的第二个参数,你可以指示该方法选择多个选项:
php
$browser->select('categories', ['Art', 'Music']);
复选框
Laravel Dusk
简介
Laravel Dusk 提供了一个富有表现力、易于使用的浏览器自动化和测试 API。默认情况下,Dusk 不需要你在本地计算机上安装 JDK 或 Selenium。相反,Dusk 使用独立的 ChromeDriver 安装。然而,你可以自由使用任何其他与 Selenium 兼容的驱动程序。
安装
要开始使用,你应该安装 Google Chrome 并将 laravel/dusk
Composer 依赖项添加到你的项目中:
shell
composer require laravel/dusk --dev
WARNING
如果你手动注册 Dusk 的服务提供程序,你永远不应该在生产环境中注册它,因为这可能会导致任意用户能够使用你的应用程序进行身份验证。
安装 Dusk 包后,执行 dusk:install
Artisan 命令。dusk:install
命令将创建一个 tests/Browser
目录、一个示例 Dusk 测试和为你的操作系统安装 Chrome Driver 二进制文件:
shell
php artisan dusk:install
接下来,在应用程序的 .env
文件中设置 APP_URL
环境变量。此值应与你在浏览器中访问应用程序时使用的 URL 匹配。
NOTE
如果你使用 Laravel Sail 来管理你的本地开发环境,请另外参阅 Sail 文档中关于配置和运行 Dusk 测试的内容。
管理 ChromeDriver 安装
如果你想安装与 Laravel Dusk 通过 dusk:install
命令安装的不同版本的 ChromeDriver,你可以使用 dusk:chrome-driver
命令:
shell
# 为你的操作系统安装最新版本的 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
WARNING
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
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
接下来,你可以修改同一类的 driver
方法以连接到你选择的 URL 和端口。此外,你可以修改应传递给 WebDriver 的"期望能力":
php
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
目录中:
shell
php artisan dusk:make LoginTest
每次测试后重置数据库
你编写的大多数测试都将与从应用程序的数据库中检索数据的页面进行交互;但是,你的 Dusk 测试永远不应该使用 RefreshDatabase
trait。RefreshDatabase
trait 利用数据库事务,这在跨 HTTP 请求时不适用或不可用。相反,你有两个选项: DatabaseMigrations
trait 和 DatabaseTruncation
trait。
使用数据库迁移
DatabaseMigrations
trait 将在每次测试之前运行你的数据库迁移。但是,为每个测试删除并重新创建数据库表通常比截断表慢:
php
<?php
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(DatabaseMigrations::class);
//
php
<?php
namespace Tests\Browser;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
//
}
WARNING
执行 Dusk 测试时不能使用 SQLite 内存数据库。由于浏览器在其自己的进程中执行,它将无法访问其他进程的内存数据库。
使用数据库截断
DatabaseTruncation
trait 将在第一次测试中迁移你的数据库,以确保你的数据库表已经正确创建。但是,在后续测试中,数据库的表将只是被截断 - 提供了比重新运行所有数据库迁移的速度优势:
php
<?php
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
uses(DatabaseTruncation::class);
//
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseTruncation;
//
}
默认情况下,此 trait 将截断除 migrations
表之外的所有表。如果你想自定义要截断的表,你可以在测试类上定义一个 $tablesToTruncate
属性:
NOTE
如果你使用 Pest,你应该在基础 DuskTestCase
类或你的测试文件扩展的任何类上定义属性或方法。
php
/**
* 指示哪些表应该被截断。
*
* @var array
*/
protected $tablesToTruncate = ['users'];
或者,你可以在测试类上定义一个 $exceptTables
属性,以指定哪些表应该从截断中排除:
php
/**
* 指示哪些表应该从截断中排除。
*
* @var array
*/
protected $exceptTables = ['users'];
要指定应截断其表的数据库连接,你可以在测试类上定义一个 $connectionsToTruncate
属性:
php
/**
* 指示哪些连接应该截断其表。
*
* @var array
*/
protected $connectionsToTruncate = ['mysql'];
如果你想在执行数据库截断之前或之后执行代码,你可以在测试类上定义 beforeTruncatingDatabase
或 afterTruncatingDatabase
方法:
php
/**
* 在数据库开始截断之前执行任何操作。
*/
protected function beforeTruncatingDatabase(): void
{
//
}
/**
* 在数据库完成截断后执行任何操作。
*/
protected function afterTruncatingDatabase(): void
{
//
}
运行测试
要运行你的浏览器测试,执行 dusk
Artisan 命令:
shell
php artisan dusk
如果你上次运行 dusk
命令时有测试失败,你可以通过首先重新运行失败的测试来节省时间,使用 dusk:fails
命令:
shell
php artisan dusk:fails
dusk
命令接受任何 Pest / PHPUnit 测试运行器通常接受的参数,例如允许你只运行给定组的测试:
shell
php artisan dusk --group=foo
NOTE
如果你使用 Laravel Sail 来管理你的本地开发环境,请参阅 Sail 文档中关于配置和运行 Dusk 测试的内容。
手动启动 ChromeDriver
默认情况下,Dusk 将自动尝试启动 ChromeDriver。如果这对你的特定系统不起作用,你可以在运行 dusk
命令之前手动启动 ChromeDriver。如果你选择手动启动 ChromeDriver,你应该注释掉 tests/DuskTestCase.php
文件中的以下行:
php
/**
* 准备进行 Dusk 测试执行。
*
* @beforeClass
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
此外,如果你在 9515 端口以外的端口上启动 ChromeDriver,你应该修改同一类的 driver
方法以反映正确的端口:
php
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
<?php
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(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');
});
});
php
<?php
namespace Tests\Browser;
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
/**
* 一个基本的浏览器测试示例。
*/
public function test_basic_example(): void
{
$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
方法的闭包中添加更多浏览器参数:
php
$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:
php
$browser->visit('/login');
你可以使用 visitRoute
方法导航到命名路由:
php
$browser->visitRoute($routeName, $parameters);
你可以使用 back
和 forward
方法"后退"和"前进":
php
$browser->back();
$browser->forward();
你可以使用 refresh
方法刷新页面:
php
$browser->refresh();
调整浏览器窗口大小
你可以使用 resize
方法调整浏览器窗口的大小:
php
$browser->resize(1920, 1080);
maximize
方法可用于最大化浏览器窗口:
php
$browser->maximize();
fitContent
方法将调整浏览器窗口以匹配其内容的大小:
php
$browser->fitContent();
当测试失败时,Dusk 将自动调整浏览器大小以适应内容,然后截图。你可以通过在测试中调用 disableFitOnFailure
方法来禁用此功能:
php
$browser->disableFitOnFailure();
你可以使用 move
方法将浏览器窗口移动到屏幕上的不同位置:
php
$browser->move($x = 100, $y = 100);
浏览器宏
如果你想定义一个自定义浏览器方法,以便在各种测试中重用,你可以在 Browser
类上使用 macro
方法。通常,你应该从应用程序的服务提供程序的 boot
方法中调用此方法:
php
<?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
实例上作为方法调用宏时,将执行宏的闭包:
php
$this->browse(function (Browser $browser) use ($user) {
$browser->visit('/pay')
->scrollToElement('#credit-card-details')
->assertSee('Enter Credit Card Details');
});
认证
通常,你将测试需要身份验证的页面。你可以使用 Dusk 的 loginAs
方法,以避免在每个测试中与应用程序的登录屏幕进行交互。loginAs
方法接受与可认证模型相关联的主键或可认证模型实例:
php
use App\Models\User;
use Laravel\Dusk\Browser;
$this->browse(function (Browser $browser) {
$browser->loginAs(User::find(1))
->visit('/home');
});
WARNING
使用 loginAs
方法后,用户会话将在文件中的所有测试中保持。
Cookies
你可以使用 cookie
方法获取或设置加密 cookie 的值。默认情况下,Laravel 创建的所有 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');
执行 JavaScript
你可以使用 script
方法在浏览器中执行任意 JavaScript 语句:
php
$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
目录中:
php
$browser->screenshot('filename');
responsiveScreenshots
方法可用于在各种断点处截取一系列截图:
php
$browser->responsiveScreenshots('filename');
screenshotElement
方法可用于截取页面上特定元素的截图:
php
$browser->screenshotElement('#selector', 'filename');
将控制台输出保存到磁盘
你可以使用 storeConsoleLog
方法将当前浏览器的控制台输出写入磁盘并使用给定的文件名。控制台输出将存储在 tests/Browser/console
目录中:
php
$browser->storeConsoleLog('filename');
将页面源代码保存到磁盘
你可以使用 storeSource
方法将当前页面的源代码写入磁盘并使用给定的文件名。页面源代码将存储在 tests/Browser/source
目录中:
php
$browser->storeSource('filename');
与元素交互
Dusk 选择器
为 Dusk 测试编写好的 CSS 选择器是最困难的部分之一。随着时间的推移,前端更改可能会导致以下选择器破坏你的测试:
php
// HTML...
<button>Login</button>
// Test...
$browser->click('.login-page .container div > button');
Dusk 选择器允许你专注于编写有效的测试,而不是记住 CSS 选择器。要定义选择器,请在 HTML 元素上添加一个 dusk
属性。然后,在与 Dusk 浏览器交互时,在选择器前加上 @
以在测试中操作附加的元素:
php
// HTML...
<button dusk="login-button">Login</button>
// Test...
$browser->click('@login-button');
如果需要,你可以通过 selectorHtmlAttribute
方法自定义 Dusk 选择器使用的 HTML 属性。通常,此方法应从应用程序的 AppServiceProvider
的 boot
方法中调用:
php
use Laravel\Dusk\Dusk;
Dusk::selectorHtmlAttribute('data-dusk');
文本、值和属性
获取和设置值
Dusk 提供了几种方法,用于与页面上元素的当前值、显示文本和属性进行交互。例如,要获取与给定 CSS 或 Dusk 选择器匹配的元素的"值",请使用 value
方法:
php
// 获取值...
$value = $browser->value('selector');
// 设置值...
$browser->value('selector', 'value');
你可以使用 inputValue
方法获取具有给定字段名称的输入元素的"值":
php
$value = $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 选择器是可选的,但我们不需要将 CSS 选择器传递给 type
方法。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有给定 name
属性的 input
或 textarea
字段。
要在不清除其内容的情况下向字段追加文本,你可以使用 append
方法:
php
$browser->type('tags', 'foo')
->append('tags', ', bar, baz');
你可以使用 clear
方法清除输入的值:
php
$browser->clear('email');
你可以指示 Dusk 慢速输入使用 typeSlowly
方法。默认情况下,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
元素上可用的值,你可以使用 select
方法。与 type
方法一样,select
方法不需要完整的 CSS 选择器。当向 select
方法传递值时,你应该传递底层选项值而不是显示文本:
php
$browser->select('size', 'Large');
你可以通过省略第二个参数来选择随机选项:
php
$browser->select('size');
通过将数组作为第二个参数传递给 select
方法,你可以指示该方法选择多个选项:
php
$browser->select('categories', ['Art', 'Music']);
复选框
要"勾选"复选框输入,你可以使用 check
方法。与许多其他输入相关方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有匹配 name
属性的复选框:
php
$browser->check('terms');
uncheck
方法可用于"取消勾选"复选框输入:
php
$browser->uncheck('terms');
单选按钮
要"选择" radio
输入选项,你可以使用 radio
方法。与许多其他输入相关方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有匹配 name
和 value
属性的 radio
输入:
php
$browser->radio('size', 'large');
附加文件
attach
方法可用于将文件附加到文件
输入元素。与许多其他与输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到匹配的 CSS 选择器,Dusk 将搜索具有匹配 name
属性的文件
输入:
php
$browser->attach('photo', __DIR__.'/photos/mountains.png');
WARNING
attach 功能要求在服务器上安装并启用 Zip
PHP 扩展。
按下按钮
该方法 press
可用于单击页面上的 button 元素。为 press
方法提供的参数可以是按钮的显示文本或 CSS / Dusk 选择器:
php
$browser->press('Login');
提交表单时,许多应用程序在按下表单的提交按钮后将其禁用,然后在表单提交的 HTTP 请求完成时重新启用该按钮。要按下按钮并等待该按钮重新启用,您可以使用 pressAndWaitFor
方法:
php
// 按下按钮并等待最多 5 秒钟以使其启用...
$browser->pressAndWaitFor('Save');
// 按下按钮并等待最多 1 秒钟以使其启用...
$browser->pressAndWaitFor('Save', 1);
单击链接
要单击链接,您可以在浏览器实例上使用 clickLink
方法。clickLink
方法将单击具有给定显示文本的链接:
php
$browser->clickLink($linkText);
您可以使用 seeLink
方法来确定具有给定显示文本的链接在页面上是否可见:
php
if ($browser->seeLink($linkText)) {
// ...
}
WARNING
这些方法与 jQuery 交互。如果 jQuery 在页面上不可用,Dusk 会自动将其注入到页面中,以便在测试期间可用。
使用键盘
keys
方法允许您为给定元素提供比 type
方法通常允许的更复杂的 Importing 序列。例如,您可以指示 Dusk 在输入值时按住修饰键。在此示例中,当 taylor
被输入到与给定选择器匹配的元素中时,将按住 shift
键。键入 taylor
后,将键入 swift
而不使用任何修饰键:
php
$browser->keys('selector', ['{shift}', 'taylor'], 'swift');
keys
方法的另一个有价值的用例是将 “keyboard shortcut” 组合发送到应用程序的主 CSS 选择器:
php
$browser->keys('.app', ['{command}', 'j']);
NOTE
所有修饰键(如 {command}
)都用 {}
字符包装,并与 Facebook\WebDriver\WebDriverKeys
类中定义的常量匹配,该常量可在 GitHub 上找到。
Fluent 键盘交互
Dusk 还提供了一个 withKeyboard
方法,允许您通过 Laravel\Dusk\Keyboard
类流畅地执行复杂的键盘交互。Keyboard
类提供 press
、release
、type
和 pause
方法:
php
use Laravel\Dusk\Keyboard;
$browser->withKeyboard(function (Keyboard $keyboard) {
$keyboard->press('c')
->pause(1000)
->release('c')
->type(['c', 'e', 'o']);
});
键盘宏
如果要定义可在整个测试套件中轻松重用的自定义键盘交互,则可以使用 Keyboard
类提供的 宏
方法。通常,您应该从服务提供商的启动``方法调用此方法:
php
<?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
实例上将宏作为方法调用时,将执行宏的闭包:
php
$browser->click('@textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->copy())
->click('@another-textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->paste());
使用鼠标
单击元素
click
方法可用于单击与给定 CSS 或 Dusk 选择器匹配的元素:
php
$browser->click('.selector');
clickAtXPath
方法可用于单击与给定 XPath 表达式匹配的元素:
php
$browser->clickAtXPath('//div[@class = "selector"]');
clickAtPoint
方法可用于单击相对于浏览器可视区域的给定坐标对处的最顶部元素:
php
$browser->clickAtPoint($x = 0, $y = 0);
doubleClick
方法可用于模拟鼠标的双击:
php
$browser->doubleClick();
$browser->doubleClick('.selector');
rightClick
方法可用于模拟鼠标的右键单击:
php
$browser->rightClick();
$browser->rightClick('.selector');
clickAndHold
方法可用于模拟单击和按住鼠标按钮。对 releaseMouse
方法的后续调用将撤消此行为并释放鼠标按钮:
php
$browser->clickAndHold('.selector');
$browser->clickAndHold()
->pause(1000)
->releaseMouse();
controlClick
方法可用于模拟浏览器中的 ctrl+click
事件:
php
$browser->controlClick();
$browser->controlClick('.selector');
鼠标悬停
当你需要将鼠标移动到与给定的 CSS 或 Dusk 选择器匹配的元素上时,可以使用 mouseover
方法:
php
$browser->mouseover('.selector');
拖放
drag
方法可用于将与给定选择器匹配的元素拖动到另一个元素:
php
$browser->drag('.from-selector', '.to-selector');
或者,您可以沿单个方向拖动元素:
php
$browser->dragLeft('.selector', $pixels = 10);
$browser->dragRight('.selector', $pixels = 10);
$browser->dragUp('.selector', $pixels = 10);
$browser->dragDown('.selector', $pixels = 10);
最后,您可以按给定的偏移量拖动元素:
php
$browser->dragOffset('.selector', $x = 10, $y = 10);
JavaScript 对话框
Dusk 提供了多种与 JavaScript 对话框交互的方法。例如,您可以使用 waitForDialog
方法等待 JavaScript 对话框出现。此方法接受一个可选参数,指示等待对话框出现的秒数:
php
$browser->waitForDialog($seconds = null);
assertDialogOpened
方法可用于断言已显示对话框并包含给定的消息:
php
$browser->assertDialogOpened('Dialog message');
如果 JavaScript 对话框包含提示,则可以使用 typeInDialog
方法在提示中键入值:
php
$browser->typeInDialog('Hello World');
要通过单击“确定”按钮关闭打开的 JavaScript 对话框,您可以调用 acceptDialog
方法:
php
$browser->acceptDialog();
要通过单击“取消”按钮关闭打开的 JavaScript 对话框,您可以调用 dismissDialog
方法:
php
$browser->dismissDialog();
与内联框架交互
如果您需要与 iframe 中的元素交互,则可以使用 withinFrame
方法。在提供给 withinFrame
方法的闭包中发生的所有元素交互都将限定为指定 iframe 的上下文:
php
$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
方法的闭包中执行的所有操作都将限定为原始选择器:
php
$browser->with('.table', function (Browser $table) {
$table->assertSee('Hello World')
->clickLink('Delete');
});
您可能偶尔需要在当前范围之外执行断言。您可以使用 elsewhere
和 elsewhereWhenAvailable
方法来完成此操作:
php
$browser->with('.table', function (Browser $table) {
// Current scope is `body .table`...
$browser->elsewhere('.page-title', function (Browser $title) {
// Current scope is `body .page-title`...
$title->assertSee('Hello World');
});
$browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
// Current scope is `body .page-title`...
$title->assertSee('Hello World');
});
});
等待元素
在测试广泛使用 JavaScript 的应用程序时,通常需要 “等待” 某些元素或数据可用,然后再继续进行测试。黄昏使这一切变得轻而易举。使用各种方法,您可以等待元素在页面上可见,甚至可以等到给定的 JavaScript 表达式计算结果为 true
。
等待
如果您只需要将测试暂停给定的毫秒数,请使用 pause
方法:
php
$browser->pause(1000);
如果只需要在给定条件为 true
时暂停测试,请使用 pauseIf
方法:
php
$browser->pauseIf(App::environment('production'), 1000);
同样,如果你需要暂停测试,除非给定条件为 true
,你可以使用 pauseUnless
方法:
php
$browser->pauseUnless(App::environment('testing'), 1000);
等待选择器
该方法的 waitFor
可用于暂停测试的执行,直到页面上显示与给定 CSS 或 Dusk 选择器匹配的元素。默认情况下,这将在引发异常之前暂停测试最多 5 秒。如有必要,您可以将自定义超时阈值作为第二个参数传递给该方法:
php
// 最多等待 5 秒钟,以便选择器...
$browser->waitFor('.selector');
// 最多等待 1 秒钟,以便选择器...
$browser->waitFor('.selector', 1);
你也可以等到与给定选择器匹配的元素包含给定的文本:
php
// 最多等待 5 秒钟,让选择器包含给定的文本...
$browser->waitForTextIn('.selector', 'Hello World');
// 最多等待 1 秒钟,让选择器包含给定的文本...
$browser->waitForTextIn('.selector', 'Hello World', 1);
您也可以等待,直到页面中缺少与给定选择器匹配的元素:
php
// 最多等待 5 秒钟,直到选择器丢失...
$browser->waitUntilMissing('.selector');
// 最多等待 1 秒钟,直到选择器丢失...
$browser->waitUntilMissing('.selector', 1);
或者,您可以等到与给定选择器匹配的元素被启用或禁用:
php
// 最多等待 5 秒,直到选择器启用...
$browser->waitUntilEnabled('.selector');
// 最多等待 1 秒钟,直到选择器启用...
$browser->waitUntilEnabled('.selector', 1);
// 最多等待 5 秒钟,直到选择器被禁用...
$browser->waitUntilDisabled('.selector');
// 最多等待 1 秒,直到选择器被禁用...
$browser->waitUntilDisabled('.selector', 1);
范围选择器(如果可用)
有时,您可能希望等待与给定选择器匹配的元素出现,然后与该元素交互。例如,您可能希望等到模态窗口可用,然后按模态窗口中的“确定”按钮。whenAvailable
方法可用于完成此操作。在给定闭包中执行的所有元素操作都将限定为原始选择器:
php
$browser->whenAvailable('.modal', function (Browser $modal) {
$modal->assertSee('Hello World')
->press('OK');
});
等待文本
方法 waitForText
可用于等待给定的文本显示在页面上:
php
// 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
方法等待显示的文本已从页面中删除:
php
// Wait a maximum of five seconds for the text to be removed...
$browser->waitUntilMissingText('Hello World');
// Wait a maximum of one second for the text to be removed...
$browser->waitUntilMissingText('Hello World', 1);
等待链接
方法 waitForLink
可用于等待给定的链接文本显示在页面上:
php
// Wait a maximum of five seconds for the link...
$browser->waitForLink('Create');
// Wait a maximum of one second for the link...
$browser->waitForLink('Create', 1);
等待输入
waitForInput
方法可用于等待给定的输入字段在页面上可见:
php
// Wait a maximum of five seconds for the input...
$browser->waitForInput($field);
// Wait a maximum of one second for the input...
$browser->waitForInput($field, 1);
正在等待页面位置
在进行路径断言(如 $browser->assertPathIs('/home')
)时,如果 window.location.pathname
正在异步更新,则断言可能会失败。您可以使用 waitForLocation
方法等待 location 为给定值:
php
$browser->waitForLocation('/secret');
该方法 waitForLocation
还可用于等待当前窗口位置成为完全限定的 URL:
php
$browser->waitForLocation('https://example.com/path');
您也可以等待命名路由的位置:
php
$browser->waitForRoute($routeName, $parameters);
等待页面重新加载
如果在执行操作后需要等待页面重新加载,请使用 waitForReload
方法:
php
use Laravel\Dusk\Browser;
$browser->waitForReload(function (Browser $browser) {
$browser->press('Submit');
})
->assertSee('Success!');
由于通常需要等待页面重新加载,因此为方便起见,您可以使用 clickAndWaitForReload
方法:
php
$browser->clickAndWaitForReload('.selector')
->assertSee('something');
等待 JavaScript 表达式
有时,您可能希望暂停测试的执行,直到给定的 JavaScript 表达式的计算结果为 true
。您可以使用 waitUntil
方法轻松完成此操作。将表达式传递给此方法时,无需包含 return
关键字或结束分号:
php
// Wait a maximum of five seconds for the expression to be true...
$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);
等待 Vue 表达式
waitUntilVue
和 waitUntilVueIsNot
方法可以用来等待 Vue 组件属性具有给定的值:
php
// Wait until the component attribute contains the given value...
$browser->waitUntilVue('user.name', 'Taylor', '@user');
// Wait until the component attribute doesn't contain the given value...
$browser->waitUntilVueIsNot('user.name', null, '@user');
等待 JavaScript 事件
waitForEvent
方法可用于暂停测试的执行,直到 JavaScript 事件发生:
php
$browser->waitForEvent('load');
事件侦听器附加到当前范围,默认情况下为 body
元素。当使用作用域选择器时,事件监听器将被附加到匹配的元素上:
php
$browser->with('iframe', function (Browser $iframe) {
// Wait for the iframe's load event...
$iframe->waitForEvent('load');
});
您还可以提供选择器作为 waitForEvent
方法的第二个参数,以将事件侦听器附加到特定元素:
php
$browser->waitForEvent('load', '.selector');
你也可以等待 document
和 window
对象上的事件:
php
// Wait until the document is scrolled...
$browser->waitForEvent('scroll', 'document');
// Wait a maximum of five seconds until the window is resized...
$browser->waitForEvent('resize', 'window', 5);
等待回调
Dusk 中的许多 “wait” 方法都依赖于底层的 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');
可用的断言
Dusk 提供了多种断言,可以用于对应用程序进行验证。所有可用的断言都记录在下面的列表中:
assertTitleassertTitleContainsassertUrlIsassertSchemeIsassertSchemeIsNotassertHostIsassertHostIsNotassertPortIsassertPortIsNotassertPathBeginsWithassertPathEndsWithassertPathContainsassertPathIsassertPathIsNotassertRouteIsassertQueryStringHasassertQueryStringMissingassertFragmentIsassertFragmentBeginsWithassertFragmentIsNotassertHasCookieassertHasPlainCookieassertCookieMissingassertPlainCookieMissingassertCookieValueassertPlainCookieValueassertSeeassertDontSeeassertSeeInassertDontSeeInassertSeeAnythingInassertSeeNothingInassertScriptassertSourceHasassertSourceMissingassertSeeLinkassertDontSeeLinkassertInputValueassertInputValueIsNotassertCheckedassertNotCheckedassertIndeterminateassertRadioSelectedassertRadioNotSelectedassertSelectedassertNotSelectedassertSelectHasOptionsassertSelectMissingOptionsassertSelectHasOptionassertSelectMissingOptionassertValueassertValueIsNotassertAttributeassertAttributeContainsassertAttributeDoesntContainassertAriaAttributeassertDataAttributeassertVisibleassertPresentassertNotPresentassertMissingassertInputPresentassertInputMissingassertDialogOpenedassertEnabledassertDisabledassertButtonEnabledassertButtonDisabledassertFocusedassertNotFocusedassertAuthenticatedassertGuestassertAuthenticatedAsassertVueassertVueIsNotassertVueContainsassertVueDoesntContain
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('/home');
assertPathEndsWith
断言当前 URL 路径以给定路径结尾:
php
$browser->assertPathEndsWith('/home');
assertPathContains
断言当前 URL 路径包含给定路径:
php
$browser->assertPathContains('/home');
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
断言 URL 的当前哈希片段与给定片段匹配:
php
$browser->assertFragmentIs('anchor');
assertFragmentBeginsWith
断言 URL 的当前哈希片段以给定片段开头:
php
$browser->assertFragmentBeginsWith('anchor');
assertFragmentIsNot
断言 URL 的当前哈希片段与给定片段不匹配:
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);
assertSeeAnythingIn
断言选择器中存在任何文本:
php
$browser->assertSeeAnythingIn($selector);
assertSeeNothingIn
断言选择器中不存在任何文本:
php
$browser->assertSeeNothingIn($selector);
assertScript
断言给定的 JavaScript 表达式的计算结果为给定值:
php
$browser->assertScript('window.isLoaded')
->assertScript('document.readyState', 'complete');
assertSourceHas
断言页面上存在给定源代码:
php
$browser->assertSourceHas($code);
assertSourceMissing
断言页面上不存在给定源代码:
php
$browser->assertSourceMissing($code);
assertSeeLink
断言页面上存在给定链接:
php
$browser->assertSeeLink($linkText);
assertDontSeeLink
断言页面上不存在给定链接:
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);
assertIndeterminate
断言给定复选框处于不确定状态:
php
$browser->assertIndeterminate($field);
assertRadioSelected
断言给定单选按钮被选中:
php
$browser->assertRadioSelected($field, $value);
assertRadioNotSelected
断言给定单选按钮未被选中:
php
$browser->assertRadioNotSelected($field, $value);
#### Global Shorthand Selectors
After installing Dusk, a base `Page` class will be placed in your `tests/Browser/Pages` directory. This class contains a `siteElements` method which may be used to define global shorthand selectors that should be available on every page throughout your application:
```php
/**
* Get the global element shortcuts for the site.
*
* @return array<string, string>
*/
public static function siteElements(): array
{
return [
'@element' => '#selector',
];
}
Page 方法
除了页面上定义的默认方法外,您还可以定义可在整个测试中使用的其他方法。例如,假设我们正在构建一个音乐管理应用程序。应用程序的一个页面的常见操作可能是创建播放列表。无需在每个测试中重写逻辑来创建播放列表,而是可以在 page 类上定义 createPlaylist
方法:
php
<?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');
}
}
定义方法后,您可以在任何使用该页面的测试中使用它。浏览器实例将自动作为第一个参数传递给自定义页面方法:
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
{
/**
* 获取组件的根选择器
*/
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
<?php
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\Browser\Components\DatePicker;
uses(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');
});
});
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
{
/**
* A basic component test example.
*/
public function test_basic_example(): void
{
$this->browse(function (Browser $browser) {
$browser->visit('/')
->within(new DatePicker, function (Browser $browser) {
$browser->selectDate(2019, 1, 30);
})
->assertSee('January');
});
}
}
持续集成
WARNING
大多数 Dusk 持续集成配置都希望您的 Laravel 应用程序使用端口 8000 上的内置 PHP 开发服务器提供服务。因此,在继续之前,您应该确保持续集成环境的 APP_URL
环境变量值为 http://127.0.0.1:8000
。
Heroku CI
要在 Heroku CI 上运行 Dusk 测试,请将以下 Google Chrome buildpack 和脚本添加到您的 Heroku app.json
文件中:
php
{
"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 服务器:
yaml
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 操作
如果您使用 GitHub Actions 运行 Dusk 测试,则可以使用以下配置文件作为起点。与 TravisCI 一样,我们将使用 php artisan serve
命令来启动 PHP 的内置 Web 服务器:
yaml
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,以便我们可以监听请求:
yaml
# 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 文档。