介绍
Laravel Dusk (opens in a new tab) 提供了一个富有表现力、易于使用的浏览器自动化和测试 API。默认情况下,Dusk 不需要您在本地计算机上安装 JDK 或 Selenium。相反,Dusk 使用独立的ChromeDriver (opens in a new tab)安装。但是,您可以自由使用您希望的任何其他与 Selenium 兼容的驱动程序。
安装
首先,您应该安装Google Chrome (opens in a new tab),并将 laravel/dusk
Composer 依赖项添加到您的项目中:
composer require laravel/dusk --dev
[!警告]
如果您手动注册 Dusk 的服务提供者,您绝不应在生产环境中注册它,因为这样做可能会导致任意用户能够对您的应用程序进行身份验证。
安装 Dusk 包后,执行 dusk:install
Artisan 命令。dusk:install
命令将创建一个 tests/Browser
目录、一个示例 Dusk 测试,并为您的操作系统安装 Chrome Driver 二进制文件:
php artisan dusk:install
接下来,在您的应用程序的 .env
文件中设置 APP_URL
环境变量。该值应与您在浏览器中访问您的应用程序使用的 URL 相匹配。
[!注意]
如果您使用Laravel Sail来管理您的本地开发环境,还请参考 Sail 文档中关于配置和运行 Dusk 测试的内容。
管理 ChromeDriver 安装
如果您想安装与 Laravel Dusk 通过 dusk:install
命令安装的不同版本的 ChromeDriver,您可以使用 dusk:chrome-driver
命令:
# 为您的操作系统安装最新版本的 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
[!警告]
Dusk 要求chromedriver
二进制文件是可执行的。如果您在运行 Dusk 时遇到问题,您应该使用以下命令确保二进制文件是可执行的:chmod -R 0755 vendor/laravel/dusk/bin/
。
使用其他浏览器
默认情况下,Dusk 使用 Google Chrome 和独立的ChromeDriver (opens in a new tab)安装来运行您的浏览器测试。但是,您可以启动自己的 Selenium 服务器,并针对您希望的任何浏览器运行您的测试。
首先,打开您的 tests/DuskTestCase.php
文件,这是您的应用程序的基本 Dusk 测试用例。在这个文件中,您可以删除对 startChromeDriver
方法的调用。这将阻止 Dusk 自动启动 ChromeDriver:
/**
* 为 Dusk 测试执行做准备。
*
* @beforeClass
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
接下来,您可以修改 driver
方法以连接到您选择的 URL 和端口。此外,您可以修改应传递给 WebDriver 的“所需功能”:
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
目录中:
php artisan dusk:make LoginTest
在每个测试后重置数据库
您编写的大多数测试将与从您的应用程序的数据库中检索数据的页面进行交互;然而,您的 Dusk 测试绝不应该使用 RefreshDatabase
特征。RefreshDatabase
特征利用数据库事务,这些事务在 HTTP 请求之间将不适用或不可用。相反,您有两个选择:DatabaseMigrations
特征和 DatabaseTruncation
特征。
使用数据库迁移
DatabaseMigrations
特征将在每个测试之前运行您的数据库迁移。然而,为每个测试删除并重新创建您的数据库表通常比截断表要慢:
<?php
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(DatabaseMigrations::class);
//
<?php
namespace Tests\Browser;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class ExampleTest extends DuskTestCase
{
use DatabaseMigrations;
//
}
[!警告]
在执行 Dusk 测试时,可能无法使用 SQLite 内存数据库。由于浏览器在其自己的进程中执行,它将无法访问其他进程的内存数据库。
使用数据库截断
DatabaseTruncation
特征将在第一个测试中迁移您的数据库,以确保您的数据库表已正确创建。然而,在后续测试中,数据库的表将简单地被截断 - 与重新运行所有数据库迁移相比,这提供了一个速度提升:
<?php
use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;
uses(DatabaseTruncation::class);
//
<?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;
//
}
默认情况下,此特征将截断除 migrations
表之外的所有表。如果您想自定义应被截断的表,您可以在您的测试类上定义一个 $tablesToTruncate
属性:
[!注意]
如果您使用 Pest,您应该在基础DuskTestCase
类或您的测试文件扩展的任何类上定义属性或方法。
/**
* 指示应截断哪些表。
*
* @var array
*/
protected $tablesToTruncate = ['users'];
或者,您可以在您的测试类上定义一个 $exceptTables
属性来指定哪些表应被排除在截断之外:
/**
* 指示应排除哪些表不进行截断。
*
* @var array
*/
protected $exceptTables = ['users'];
要指定应截断其表的数据库连接,您可以在您的测试类上定义一个 $connectionsToTruncate
属性:
/**
* 指示应截断哪些连接的表。
*
* @var array
*/
protected $connectionsToTruncate = ['mysql'];
如果您想在执行数据库截断之前或之后执行代码,您可以在您的测试类上定义 beforeTruncatingDatabase
或 afterTruncatingDatabase
方法:
/**
* 在数据库开始截断之前执行任何应进行的工作。
*/
protected function beforeTruncatingDatabase(): void
{
//
}
/**
* 在数据库完成截断之后执行任何应进行的工作。
*/
protected function afterTruncatingDatabase(): void
{
//
}
运行测试
要运行您的浏览器测试,执行 dusk
Artisan 命令:
php artisan dusk
如果您上次运行 dusk
命令时有测试失败,您可以使用 dusk:fails
命令首先重新运行失败的测试,以节省时间:
php artisan dusk:fails
dusk
命令接受通常由 Pest / PHPUnit 测试运行器接受的任何参数,例如允许您仅为给定的组 (opens in a new tab)运行测试:
php artisan dusk --group=foo
[!注意]
如果您使用Laravel Sail来管理您的本地开发环境,请参考 Sail 文档中关于配置和运行 Dusk 测试的内容。
手动启动 ChromeDriver
默认情况下,Dusk 将自动尝试启动 ChromeDriver。如果这对您的特定系统不起作用,您可以在运行 dusk
命令之前手动启动 ChromeDriver。如果您选择手动启动 ChromeDriver,您应该注释掉您的 tests/DuskTestCase.php
文件中的以下行:
/**
* 为 Dusk 测试执行做准备。
*
* @beforeClass
*/
public static function prepare(): void
{
// static::startChromeDriver();
}
此外,如果您在除 9515 以外的端口上启动 ChromeDriver,您应该修改同一类的 driver
方法以反映正确的端口:
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
use App\Models\User;
use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;
uses(DatabaseMigrations::class);
test('基本示例', 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
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
方法的闭包的签名中添加更多的浏览器参数:
$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:
$browser->visit('/login');
您可以使用 visitRoute
方法导航到命名路由:
$browser->visitRoute($routeName, $parameters);
您可以使用 back
和 forward
方法向后和向前导航:
$browser->back();
$browser->forward();
您可以使用 refresh
方法刷新页面:
$browser->refresh();
调整浏览器窗口大小
您可以使用 resize
方法调整浏览器窗口的大小:
$browser->resize(1920, 1080);
您可以使用 maximize
方法最大化浏览器窗口:
$browser->maximize();
您可以使用 fitContent
方法将浏览器窗口调整为与其内容的大小相匹配:
$browser->fitContent();
当测试失败时,Dusk 将在截图之前自动调整浏览器大小以适应内容。您可以通过在您的测试中调用 disableFitOnFailure
方法来禁用此功能:
$browser->disableFitOnFailure();
您可以使用 move
方法将浏览器窗口移动到您屏幕上的不同位置:
复选框
要“选中”一个复选框输入,您可以使用 check
方法。与许多其他与输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有匹配 name
属性的复选框:
$browser->check('terms');
uncheck
方法可用于“取消选中”复选框输入:
$browser->uncheck('terms');
单选按钮
要“选择”一个 radio
输入选项,您可以使用 radio
方法。与许多其他与输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有匹配 name
和 value
属性的 radio
输入:
$browser->radio('size', 'large');
附加文件
attach
方法可用于将文件附加到 file
输入元素。与许多其他与输入相关的方法一样,不需要完整的 CSS 选择器。如果找不到 CSS 选择器匹配项,Dusk 将搜索具有匹配 name
属性的 file
输入:
$browser->attach('photo', __DIR__.'/photos/mountains.png');
[!WARNING]
attach
函数要求在服务器上安装并启用Zip
PHP 扩展。
按下按钮
press
方法可用于点击页面上的按钮元素。传递给 press
方法的参数可以是按钮的显示文本或 CSS / Dusk 选择器:
$browser->press('Login');
当提交表单时,许多应用程序在按下表单的提交按钮后会禁用该按钮,然后在表单提交的 HTTP 请求完成后重新启用该按钮。要按下按钮并等待按钮重新启用,您可以使用 pressAndWaitFor
方法:
// 按下按钮并等待最多 5 秒使其被启用...
$browser->pressAndWaitFor('Save');
// 按下按钮并等待最多 1 秒使其被启用...
$browser->pressAndWaitFor('Save', 1);
点击链接
要点击链接,您可以在浏览器实例上使用 clickLink
方法。clickLink
方法将点击具有给定显示文本的链接:
$browser->clickLink($linkText);
您可以使用 seeLink
方法来确定页面上是否存在具有给定显示文本的可见链接:
if ($browser->seeLink($linkText)) {
//...
}
[!WARNING]
这些方法与 jQuery 交互。如果页面上没有 jQuery,Dusk 将自动将其注入页面,以便在测试期间可用。
使用键盘
keys
方法允许您向给定元素提供比 type
方法通常允许的更复杂的输入序列。例如,您可以指示 Dusk 在输入值时按住修饰键。在这个例子中,在将 taylor
输入到与给定选择器匹配的元素时,将按住 shift
键。输入 taylor
后,将在没有任何修饰键的情况下输入 swift
:
$browser->keys('selector', ['{shift}', 'taylor'], 'swift');
keys
方法的另一个有价值的用例是向应用程序的主要 CSS 选择器发送“键盘快捷键”组合:
$browser->keys('.app', ['{command}', 'j']);
[!NOTE]
所有修饰键(如{command}
)都包装在{}
字符中,并与Facebook\WebDriver\WebDriverKeys
类中定义的常量匹配,该类可以在 GitHub (opens in a new tab) 上找到。
流畅的键盘交互
Dusk 还提供了 withKeyboard
方法,允许您通过 Laravel\Dusk\Keyboard
类流畅地执行复杂的键盘交互。Keyboard
类提供 press
、release
、type
和 pause
方法:
use Laravel\Dusk\Keyboard;
$browser->withKeyboard(function (Keyboard $keyboard) {
$keyboard->press('c')
->pause(1000)
->release('c')
->type(['c', 'e', 'o']);
});
键盘宏
如果您想定义自定义键盘交互,以便在整个测试套件中轻松重复使用,您可以使用 Keyboard
类提供的 macro
方法。通常,您应该从 服务提供者的 boot
方法中调用此方法:
<?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
实例上将宏作为方法调用时,将执行宏的闭包:
$browser->click('@textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->copy())
->click('@another-textarea')
->withKeyboard(fn (Keyboard $keyboard) => $keyboard->paste());
使用鼠标
点击元素
click
方法可用于点击与给定 CSS 或 Dusk 选择器匹配的元素:
$browser->click('.selector');
clickAtXPath
方法可用于点击与给定 XPath 表达式匹配的元素:
$browser->clickAtXPath('//div[@class = "selector"]');
clickAtPoint
方法可用于点击相对于浏览器可视区域的给定坐标对的最顶层元素:
$browser->clickAtPoint($x = 0, $y = 0);
doubleClick
方法可用于模拟鼠标的双击:
$browser->doubleClick();
$browser->doubleClick('.selector');
rightClick
方法可用于模拟鼠标的右键单击:
$browser->rightClick();
$browser->rightClick('.selector');
clickAndHold
方法可用于模拟鼠标按钮被点击并按住。后续调用 releaseMouse
方法将撤销此行为并释放鼠标按钮:
$browser->clickAndHold('.selector');
$browser->clickAndHold()
->pause(1000)
->releaseMouse();
controlClick
方法可用于模拟浏览器内的 ctrl+click
事件:
$browser->controlClick();
$browser->controlClick('.selector');
鼠标悬停
当您需要将鼠标移动到与给定 CSS 或 Dusk 选择器匹配的元素上时,可以使用 mouseover
方法:
$browser->mouseover('.selector');
拖放
drag
方法可用于将与给定选择器匹配的元素拖到另一个元素:
$browser->drag('.from-selector', '.to-selector');
或者,您可以在单个方向上拖动元素:
$browser->dragLeft('.selector', $pixels = 10);
$browser->dragRight('.selector', $pixels = 10);
$browser->dragUp('.selector', $pixels = 10);
$browser->dragDown('.selector', $pixels = 10);
最后,您可以通过给定的偏移量拖动元素:
$browser->dragOffset('.selector', $x = 10, $y = 10);
JavaScript 对话框
Dusk 提供了各种方法来与 JavaScript 对话框进行交互。例如,您可以使用 waitForDialog
方法等待 JavaScript 对话框出现。此方法接受一个可选参数,指示等待对话框出现的秒数:
$browser->waitForDialog($seconds = null);
assertDialogOpened
方法可用于断言已显示一个对话框并包含给定的消息:
$browser->assertDialogOpened('Dialog message');
如果 JavaScript 对话框包含提示,您可以使用 typeInDialog
方法在提示中输入值:
$browser->typeInDialog('Hello World');
要通过点击“确定”按钮关闭打开的 JavaScript 对话框,您可以调用 acceptDialog
方法:
$browser->acceptDialog();
要通过点击“取消”按钮关闭打开的 JavaScript 对话框,您可以调用 dismissDialog
方法:
$browser->dismissDialog();
与内联框架交互
如果您需要与 iframe 内的元素进行交互,您可以使用 withinFrame
方法。提供给 withinFrame
方法的闭包内发生的所有元素交互都将局限于指定 iframe 的上下文:
$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
方法的闭包内执行的所有操作都将局限于原始选择器:
$browser->with('.table', function (Browser $table) {
$table->assertSee('Hello World')
->clickLink('Delete');
});
您可能偶尔需要在当前作用域之外执行断言。您可以使用 elsewhere
和 elsewhereWhenAvailable
方法来实现此目的:
$browser->with('.table', function (Browser $table) {
// 当前作用域是 `body.table`...
$browser->elsewhere('.page-title', function (Browser $title) {
// 当前作用域是 `body.page-title`...
$title->assertSee('Hello World');
});
$browser->elsewhereWhenAvailable('.page-title', function (Browser $title) {
// 当前作用域是 `body.page-title`...
$title->assertSee('Hello World');
});
});
等待元素
在测试广泛使用 JavaScript 的应用程序时,通常需要在继续测试之前“等待”某些元素或数据可用。Dusk 使这变得轻而易举。使用各种方法,您可以等待元素在页面上变得可见,甚至等待直到给定的 JavaScript 表达式计算结果为 true
。
等待
如果您只需要将测试暂停给定的毫秒数,请使用 pause
方法:
$browser->pause(1000);
如果您需要仅在给定条件为 true
时暂停测试,请使用 pauseIf
方法:
$browser->pauseIf(App::environment('production'), 1000);
同样,如果您需要除非给定条件为 true
否则暂停测试,您可以使用 pauseUnless
方法:
$browser->pauseUnless(App::environment('testing'), 1000);
等待选择器
waitFor
方法可用于暂停测试的执行,直到与给定 CSS 或 Dusk 选择器匹配的元素显示在页面上。默认情况下,如果在抛出异常之前测试将暂停最多五秒钟。如果需要,您可以将自定义超时阈值作为方法的第二个参数传递:
// 等待最多五秒钟以找到选择器...
$browser->waitFor('.selector');
// 等待最多一秒钟以找到选择器...
$browser->waitFor('.selector', 1);
您还可以等待直到与给定选择器匹配的元素包含给定的文本:
// 等待最多五秒钟以找到选择器包含给定的文本...
$browser->waitForTextIn('.selector', 'Hello World');
// 等待最多一秒钟以找到选择器包含给定的文本...
$browser->waitForTextIn('.selector', 'Hello World', 1);
您还可以等待直到与给定选择器匹配的元素从页面中消失:
// 等待最多五秒钟直到选择器消失...
$browser->waitUntilMissing('.selector');
// 等待最多一秒钟直到选择器消失...
$browser->waitUntilMissing('.selector', 1);
或者,您可以等待直到与给定选择器匹配的元素被启用或禁用:
// 等待最多五秒钟直到选择器被启用...
$browser->waitUntilEnabled('.selector');
// 等待最多一秒钟直到选择器被启用...
$browser->waitUntilEnabled('.selector', 1);
// 等待最多五秒钟直到选择器被禁用...
$browser->waitUntilDisabled('.selector');
// 等待最多一秒钟直到选择器被禁用...
$browser->waitUntilDisabled('.selector', 1);
当选择器可用时作用域选择器
有时,您可能希望等待与给定选择器匹配的元素出现,然后与该元素进行交互。例如,您可能希望等待模态窗口可用,然后在模态窗口内按下“确定”按钮。可以使用 whenAvailable
方法来实现此目的。给定闭包内执行的所有元素操作都将局限于原始选择器:
$browser->whenAvailable('.modal', function (Browser $modal) {
$modal->assertSee('Hello World')
->press('OK');
});
等待文本
waitForText
方法可用于等待给定的文本显示在页面上:
// 等待最多五秒钟以找到文本...
$browser->waitForText('Hello World');
// 等待最多一秒钟以找到文本...
$browser->waitForText('Hello World', 1);
您可以使用 waitUntilMissingText
方法等待显示的文本从页面中删除:
// 等待最多五秒钟以删除文本...
$browser->waitUntilMissingText('Hello World');
// 等待最多一秒钟以删除文本...
$browser->waitUntilMissingText('Hello World', 1);
等待链接
waitForLink
方法可用于等待给定的链接文本显示在页面上:
// 等待最多五秒钟以找到链接...
$browser->waitForLink('Create');
// 等待最多一秒钟以找到链接...
$browser->waitForLink('Create', 1);
等待输入
waitForInput
方法可用于等待给定的输入字段在页面上可见:
// 等待最多五秒钟以找到输入...
$browser->waitForInput($field);
// 等待最多一秒钟以找到输入...
$browser->waitForInput($field, 1);
等待页面位置
当进行路径断言(如 $browser->assertPathIs('/home')
)时,如果 window.location.pathname
正在异步更新,则断言可能会失败。您可以使用 waitForLocation
方法等待位置为给定值:
$browser->waitForLocation('/secret');
waitForLocation
方法还可用于等待当前窗口位置为完全限定的 URL:
$browser->waitForLocation('https://example.com/path');
您还可以等待 命名路由的 位置:
$browser->waitForRoute($routeName, $parameters);
等待页面重新加载
如果您需要在执行操作后等待页面重新加载,请使用 waitForReload
方法:
use Laravel\Dusk\Browser;
$browser->waitForReload(function (Browser $browser) {
$browser->press('Submit');
})
->assertSee('Success!');
由于通常在点击按钮后需要等待页面重新加载,因此您可以方便地使用 clickAndWaitForReload
方法:
$browser->clickAndWaitForReload('.selector')
->assertSee('something');
等待 JavaScript 表达式
有时您可能希望暂停测试的执行,直到给定的 JavaScript 表达式计算结果为 true
。您可以使用 waitUntil
方法轻松实现此目的。将表达式传递给此方法时,您不需要包含 return
关键字或结尾分号:
// 等待最多五秒钟以使表达式为真...
$browser->waitUntil('App.data
#### `assertPathIs`
断言当前路径与给定路径匹配:
```php
$browser->assertPathIs('/home');
assertPathIsNot
断言当前路径与给定路径不匹配:
$browser->assertPathIsNot('/home');
assertRouteIs
断言当前 URL 与给定的命名路由的 URL 匹配:
$browser->assertRouteIs($name, $parameters);
assertQueryStringHas
断言给定的查询字符串参数存在:
$browser->assertQueryStringHas($name);
断言给定的查询字符串参数存在且具有给定值:
$browser->assertQueryStringHas($name, $value);
assertQueryStringMissing
断言给定的查询字符串参数不存在:
$browser->assertQueryStringMissing($name);
assertFragmentIs
断言 URL 的当前哈希片段与给定片段匹配:
$browser->assertFragmentIs('anchor');
assertFragmentBeginsWith
断言 URL 的当前哈希片段以给定片段开头:
$browser->assertFragmentBeginsWith('anchor');
assertFragmentIsNot
断言 URL 的当前哈希片段与给定片段不匹配:
$browser->assertFragmentIsNot('anchor');
assertHasCookie
断言给定的加密 Cookie 存在:
$browser->assertHasCookie($name);
assertHasPlainCookie
断言给定的未加密 Cookie 存在:
$browser->assertHasPlainCookie($name);
assertCookieMissing
断言给定的加密 Cookie 不存在:
$browser->assertCookieMissing($name);
assertPlainCookieMissing
断言给定的未加密 Cookie 不存在:
$browser->assertPlainCookieMissing($name);
assertCookieValue
断言加密 Cookie 具有给定值:
$browser->assertCookieValue($name, $value);
assertPlainCookieValue
断言未加密 Cookie 具有给定值:
$browser->assertPlainCookieValue($name, $value);
assertSee
断言给定的文本在页面上存在:
$browser->assertSee($text);
assertDontSee
断言给定的文本在页面上不存在:
$browser->assertDontSee($text);
assertSeeIn
断言给定的文本在选择器内存在:
$browser->assertSeeIn($selector, $text);
assertDontSeeIn
断言给定的文本在选择器内不存在:
$browser->assertDontSeeIn($selector, $text);
assertSeeAnythingIn
断言选择器内存在任何文本:
$browser->assertSeeAnythingIn($selector);
assertSeeNothingIn
断言选择器内不存在任何文本:
$browser->assertSeeNothingIn($selector);
assertScript
断言给定的 JavaScript 表达式计算结果为给定值:
$browser->assertScript('window.isLoaded')
->assertScript('document.readyState', 'complete');
assertSourceHas
断言给定的源代码在页面上存在:
$browser->assertSourceHas($code);
assertSourceMissing
断言给定的源代码在页面上不存在:
$browser->assertSourceMissing($code);
assertSeeLink
断言给定的链接在页面上存在:
$browser->assertSeeLink($linkText);
assertDontSeeLink
断言给定的链接在页面上不存在:
$browser->assertDontSeeLink($linkText);
assertInputValue
断言给定的输入字段具有给定值:
$browser->assertInputValue($field, $value);
assertInputValueIsNot
断言给定的输入字段不具有给定值:
$browser->assertInputValueIsNot($field, $value);
assertChecked
断言给定的复选框被选中:
$browser->assertChecked($field);
assertNotChecked
断言给定的复选框未被选中:
$browser->assertNotChecked($field);
assertIndeterminate
断言给定的复选框处于不确定状态:
$browser->assertIndeterminate($field);
assertRadioSelected
断言给定的单选字段被选中:
$browser->assertRadioSelected($field, $value);
assertRadioNotSelected
断言给定的单选字段未被选中:
$browser->assertRadioNotSelected($field, $value);
assertSelected
断言给定的下拉列表中选择了给定值:
$browser->assertSelected($field, $value);
assertNotSelected
断言给定的下拉列表中未选择给定值:
$browser->assertNotSelected($field, $value);
assertSelectHasOptions
断言给定的值数组可用于选择:
$browser->assertSelectHasOptions($field, $values);
assertSelectMissingOptions
断言给定的值数组不可用于选择:
$browser->assertSelectMissingOptions($field, $values);
assertSelectHasOption
断言给定的值可在给定字段上选择:
$browser->assertSelectHasOption($field, $value);
assertSelectMissingOption
断言给定的值不可选择:
$browser->assertSelectMissingOption($field, $value);
assertValue
断言与给定选择器匹配的元素具有给定值:
$browser->assertValue($selector, $value);
assertValueIsNot
断言与给定选择器匹配的元素不具有给定值:
$browser->assertValueIsNot($selector, $value);
assertAttribute
断言与给定选择器匹配的元素在提供的属性中具有给定值:
$browser->assertAttribute($selector, $attribute, $value);
assertAttributeContains
断言与给定选择器匹配的元素在提供的属性中包含给定值:
$browser->assertAttributeContains($selector, $attribute, $value);
assertAttributeDoesntContain
断言与给定选择器匹配的元素在提供的属性中不包含给定值:
$browser->assertAttributeDoesntContain($selector, $attribute, $value);
assertAriaAttribute
断言与给定选择器匹配的元素在提供的 aria
属性中具有给定值:
例如,给定标记 <button aria-label="Add"></button>
,您可以像这样对 aria-label
属性进行断言:
$browser->assertAriaAttribute('button', 'label', 'Add')
assertDataAttribute
断言与给定选择器匹配的元素在提供的数据属性中具有给定值:
例如,给定标记 <tr id="row-1" data-content="attendees"></tr>
,您可以像这样对 data-label
属性进行断言:
$browser->assertDataAttribute('#row-1', 'content', 'attendees')
assertVisible
断言与给定选择器匹配的元素可见:
$browser->assertVisible($selector);
assertPresent
断言与给定选择器匹配的元素在源中存在:
$browser->assertPresent($selector);
assertNotPresent
断言与给定选择器匹配的元素在源中不存在:
$browser->assertNotPresent($selector);
assertMissing
断言与给定选择器匹配的元素不可见:
$browser->assertMissing($selector);
assertInputPresent
断言具有给定名称的输入存在:
$browser->assertInputPresent($name);
assertInputMissing
断言具有给定名称的输入在源中不存在:
$browser->assertInputMissing($name);
assertDialogOpened
断言具有给定消息的 JavaScript 对话框已打开:
$browser->assertDialogOpened($message);
assertEnabled
断言给定字段已启用:
$browser->assertEnabled($field);
assertDisabled
断言给定字段已禁用:
$browser->assertDisabled($field);
assertButtonEnabled
断言给定按钮已启用:
$browser->assertButtonEnabled($button);
assertButtonDisabled
断言给定按钮已禁用:
$browser->assertButtonDisabled($button);
assertFocused
断言给定字段已获得焦点:
$browser->assertFocused($field);
assertNotFocused
断言给定字段未获得焦点:
$browser->assertNotFocused($field);
assertAuthenticated
断言用户已通过身份验证:
$browser->assertAuthenticated();
assertGuest
断言用户未通过身份验证:
$browser->assertGuest();
assertAuthenticatedAs
断言用户已作为给定用户通过身份验证:
$browser->assertAuthenticatedAs($user);
assertVue
Dusk 甚至允许您对Vue 组件 (opens in a new tab)数据的状态进行断言。例如,假设您的应用程序包含以下 Vue 组件:
<!-- HTML... -->
<profile dusk="profile-component"></profile>
<!-- 组件定义... -->
Vue.component('profile', {
template: '<div>{{ user.name }}</div>',
data: function () {
return {
user: {
name: 'Taylor'
}
};
}
});
您可以像这样对 Vue 组件的状态进行断言:
test('vue', function () {
$this->browse(function (Browser $browser) {
$browser->visit('/')
->assertVue('user.name', 'Taylor', '@profile-component');
});
});
/**
* 一个基本的 Vue 测试示例
*/
public function test_vue(): void
{
$this->browse(function (Browser $browser) {
$browser->visit('/')
->assertVue('user.name', 'Taylor', '@profile-component');
});
}
assertVueIsNot
断言给定的 Vue 组件数据属性与给定值不匹配:
$browser->assertVueIsNot($property, $value, $componentSelector = null);
assertVueContains
断言给定的 Vue 组件数据属性是一个数组且包含给定值:
$browser->assertVueContains($property, $value, $componentSelector = null);
assertVueDoesntContain
断言给定的 Vue 组件数据属性是一个数组且不包含给定值:
$browser->assertVueDoesntContain($property, $value, $componentSelector = null);
页面
有时,测试需要按顺序执行几个复杂的操作。这可能会使您的测试更难阅读和理解。Dusk 页面允许您定义富有表现力的操作,然后可以通过单个方法在给定页面上执行。页面还允许您为应用程序或单个页面定义常见选择器的快捷方式。
生成页面
要生成页面对象,请执行 dusk:page
Artisan 命令。所有页面对象都将放置在应用程序的 tests/Browser/Pages
目录中:
php artisan dusk:page Login
配置页面
默认情况下,页面有三个方法:url
、assert
和 elements
。我们现在将讨论 url
和 assert
方法。elements
方法将在下面的快捷选择器部分进行更详细的讨论。
url
方法
url
方法应返回表示页面的 URL 的路径。Dusk 在浏览器中导航到该页面时将使用此 URL:
/**
* 获取页面的 URL
*/
public function url(): string
{
return '/login';
}
assert
方法
assert
方法可以进行任何必要的断言,以验证浏览器实际上是否在给定页面上。实际上,此方法中不一定要放置任何内容;但是,如果您愿意,可以进行这些断言。当导航到该页面时,这些断言将自动运行:
/**
* 断言浏览器在该页面上
*/
public function assert(Browser $browser): void
{
$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 选择器定义快速、易于记忆的快捷方式。例如,让我们为应用程序登录页面的“电子邮件”输入字段定义一个快捷方式:
/**
* 获取页面的元素快捷方式
*
* @return array<string, string>
*/
public function elements(): array
{
return [
'@email' => 'input[name=email]',
];
}
一旦定义了快捷方式,您就可以在通常使用完整 CSS 选择器的任何地方使用快捷选择器:
$browser->type('@email', 'taylor@laravel.com');
全局快捷选择器
安装 Dusk 后,一个基本的 Page
类将放置在您的 tests/Browser/Pages
目录中。这个类包含一个 siteElements
方法,可用于定义全局快捷选择器,这些快捷选择器应该在您的应用程序的每个页面上都可用:
/**
* 获取站点的全局元素快捷方式
*
* @return array<string, string>
*/
public static function siteElements(): array
{
return [
'@element' => '#selector',
];
}
页面方法
除了页面上定义的默认方法外,您还可以定义其他方法,这些方法可以在整个测试中使用。例如,假设我们正在构建一个音乐管理应用程序。应用程序的一个页面的常见操作可能是创建一个播放列表。您可以在页面类上定义一个 createPlaylist
方法,而不是在每个测试中重写创建播放列表的逻辑:
<?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');
}
}
一旦定义了该方法,您就可以在使用该页面的任何测试中使用它。浏览器实例将自动作为第一个参数传递给自定义页面方法:
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 artisan dusk:component DatePicker
如上所示,“日期选择器”是一个可能在您的应用程序的各种页面上存在的组件的示例。在整个测试套件的数十个测试中手动编写选择日期的浏览器自动化逻辑可能会变得很麻烦。相反,我们可以定义一个 Dusk 组件来表示日期选择器,从而将该逻辑封装在组件中:
<?php
namespace Tests\Browser\Components;
use Laravel\Dusk\Browser;
use Laravel\Dusk\Component as BaseComponent;
class DatePicker extends BaseComponent
{