lmc/steward

Steward - 使 Selenium WebDriver + PHPUnit 测试变得简单且健壮

3.1.0 2023-07-20 11:51 UTC

README

Latest Stable Version GitHub Actions Build Status AppVeyor Build Status Coverage Status Total Downloads

Steward 是一套库,旨在简化使用 Selenium WebDriver 在 PHPUnit 中编写和运行健壮的功能系统测试。

Steward 的优点是什么?

  • 它允许您在一分钟内开始编写复杂的测试用例。
  • 它为您做了大量工作
    • 使用一条命令下载并安装 Selenium 服务器
    • 设置您选择的浏览器
    • 在失败的断言上自动截图
    • 以 JUnit 格式生成测试结果(易于处理,例如 Jenkins 和其他工具)
    • 等等...
  • 测试并行运行,因此唯一的瓶颈是同时启动的 Selenium 节点数量。
  • 简单的语法糖层在默认的 WebDriver 命令 之上,有助于缩短您的测试并提高可读性。
  • 如果您已经使用 PHP,您不需要学习新语言来编写功能测试。此外,如果您熟悉单元测试和 PHPUnit,您就知道了。
  • 允许您规划测试依赖关系。
    • 例如,如果您需要在测试结果之前等待 2 分钟直到某个事件通过您的消息队列?没问题!测试的顺序被优化以最小化总执行时间。
  • 在测试执行期间可以清楚地查看测试状态,因此您将很容易知道已经完成了多少测试以及它们的结果。
  • 您可以通过向 EventDispatcher 注册自定义事件来轻松扩展 Steward。
    • 例如,您可以添加自定义配置选项或更改传递给子 PHPUnit 进程的参数。
  • 云服务如 Sauce LabsBrowserStackTestingBot 完全集成,让您有机会在不设置自己的基础设施的情况下运行测试。
  • Steward 已经过现场测试 - 我们每天在我们的 公司 中使用它来维护我们产品的质量,这得益于数百个测试用例。该库本身也广泛覆盖了单元测试。
  • Steward 建立在稳固的基础上:WebDriver 是浏览器自动化的 W3C 草案标准,php-webdriver 是最常用和发展的 Selenium 语言绑定,PHPUnit 是一个知名且广泛使用的测试框架,而 Symfony Console 是 PHP CLI 应用的行业标准。

示例用法

要了解如何使用和扩展 Steward,请查看我们的 示例项目

变更日志

有关最新更改,请参阅 CHANGELOG.md 文件。我们遵循 语义版本控制

入门指南

1. 安装 Steward

在大多数情况下,我们建议将功能测试放在与您的应用程序相同的存储库中,但要在单独的文件夹中。我们建议将它们放在 selenium-tests/ 目录中。

在此目录下,只需使用以下命令安装 Steward:

$ composer require lmc/steward

注意:您需要安装 Composer 才能执行此操作。

2. 下载 Selenium 服务器和浏览器驱动程序

以下步骤仅适用于您想在本机上下载并运行 Selenium Standalone 服务器与测试浏览器的情况。另一种可能性是在 Docker 容器中启动 Selenium 服务器和测试浏览器

获取 Selenium Standalone 服务器

您需要下载 Selenium 服务器,以便它可以在指定的浏览器中执行命令。在测试的根目录下(例如 selenium-tests/),只需运行

$ ./vendor/bin/steward install

这将检查 Selenium Standalone 服务器最新版本并为您下载(jar 文件将放置在 ./vendor/bin 目录中)。

您可以将此命令作为 CI 服务器构建的一部分运行,然后使用 --no-interaction 选项下载 Selenium,无需任何交互,并以 jar 文件的绝对路径作为唯一输出。

下载浏览器驱动程序

如果您的系统上尚未安装,您将需要下载用于测试的浏览器(s)的 Selenium 驱动程序。有关更多信息,请参阅我们的维基中的 Selenium 服务器 & 浏览器驱动程序

3. 编写第一个测试

为了提供 Steward 功能,您的测试必须扩展 Lmc\Steward\Test\AbstractTestCase 类。

您还必须配置 PSR-4 自动加载,以便 Steward 可以找到您的测试。只需在您的 composer.json 文件中添加以下内容即可

    "autoload": {
        "psr-4": {
            "My\\": "tests/"
        }
    }

别忘了创建 selenium-tests/tests/ 目录,并在之后运行 composer dump-autoload

对于测试本身,将其放置在 selenium-tests/tests/ 目录中

<?php
// selenium-tests/tests/TitlePageTest.php

namespace My; // Note the "My" namespace maps to the "tests" folder, as defined in the autoload part of `composer.json`.

use Facebook\WebDriver\WebDriverBy;
use Lmc\Steward\Test\AbstractTestCase;

class TitlePageTest extends AbstractTestCase
{
    public function testShouldContainSearchInput()
    {
        // Load the URL (will wait until page is loaded)
        $this->wd->get('https://www.w3.org/'); // $this->wd holds instance of \RemoteWebDriver

        // Do some assertion
        $this->assertContains('W3C', $this->wd->getTitle());

        // You can use $this->log(), $this->warn() or $this->debug() with sprintf-like syntax
        $this->log('Current page "%s" has title "%s"', $this->wd->getCurrentURL(), $this->wd->getTitle());

        // Make sure search input is present
        $searchInput = $this->wd->findElement(WebDriverBy::cssSelector('#search-form input'));
        // Or you can use syntax sugar provided by Steward (this is equivalent of previous line)
        $searchInput = $this->findByCss('#search-form input');

        // Assert title of the search input
        $this->assertEquals('Search', $searchInput->getAttribute('title'));
    }
}

4. 运行您的测试

启动 Selenium 服务器

现在您需要启动 Selenium 服务器,它将监听并执行从您的测试发送的命令。

$ java -jar ./vendor/bin/selenium-server-4.10.0.jar standalone # the version may differ

这将启动单个 Selenium 服务器实例(在端口 4444 上监听),以独立(别名 "no-grid")模式运行(意味着服务器将接收并执行命令,而不会分发到节点)。

注意:您可能希望以网格模式运行 Selenium 服务器。这有一个 hub 接收命令,而多个 nodes 执行它们。请参阅 Selenium Grid 文档。

运行 Steward!

现在 Selenium 服务器正在监听,让我们启动您的测试!使用 run 命令

./vendor/bin/steward run staging firefox

片刻之后,您应该看到一个 Firefox 窗口出现,然后 https://www.w3.org/ 网站应该被加载到窗口立即关闭之前。查看命令输出以检查测试结果。

run 命令有两个必需的参数:环境和浏览器

  • 默认情况下,环境参数没有效果,但在您的测试中它是可访问的,这使得更改测试网站的基准 URL 等操作变得容易。这对于在本地服务器和预发布环境之间进行测试非常有用。
  • 浏览器名称可以是Selenium支持的任何浏览器名称。最常见的是"firefox"、"chrome"、"phantomjs"、"safari"和"internet explorer"。有关安装浏览器驱动程序的更多信息,请参阅我们的维基百科页面安装浏览器驱动程序

对于run命令还有一些有用的选项

  • --group - 仅运行特定组(或多组)的测试
  • --exclude-group - 排除某些组(或多组)的测试(甚至可以与--group结合使用)
  • --server-url - 设置与默认URL不同的Selenium服务器URL(默认为http://localhost:4444
  • --xdebug - 在您的测试中启动Xdebug调试器。允许您从IDE中调试测试(在我们的维基百科页面了解有关测试调试的更多信息
  • --capability - 直接将任何额外的能力传递给Selenium WebDriver服务器(有关更多信息,请参阅维基百科页面设置自定义能力
  • --parallel-limit - 限制并行执行的测试用例数量(默认为50)
  • --help - 查看所有其他选项和默认值
  • 调整输出级别:默认情况下,只将测试结果摘要打印到输出;可以通过以下方式更改详细程度
    • -v - 立即输出失败的测试名称
    • -vv - 在运行期间也打印进度信息(哪些测试已开始/完成等);如果任何测试失败,其输出将打印到控制台
    • -vvv - 输出一切,包括所有测试输出

5. 查看结果和截图

日志将打印到您运行run命令的控制台。这可能会有些混乱,尤其是如果您并行运行多个测试。

作为解决方案,每个测试用例都有一个JUnit XML格式的单独文件,位于logs/目录中。截图和HTML快照也保存在此目录中(在失败的断言或WebDriver命令失败时自动生成)。

要查看测试执行期间(或之后)的当前测试状态,请在浏览器中打开logs/results.xml文件

Example output as displayed in logs/results.xml file

可以使用./vendor/bin/steward results命令在命令行界面获得类似输出(见下文)。您还可以添加-vvv以查看每个单独测试的结果。

Example output of results command

6. 查看测试执行时间线

Steward提供测试执行时间线的可视化表示。当与在"网格"模式下使用的Selenium服务器一起使用时,您可以查看哪个Selenium节点执行了哪个测试用例,识别可能的瓶颈等。

要生成时间线,只需在测试构建完成后运行generate-timeline命令

./vendor/bin/steward generate-timeline

将生成timeline.html文件,并将其放置在logs/目录中。

Example timeline visualization

许可证

Steward是开源软件,根据MIT许可证授权。