README

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

Steward 的优点是什么？

• 它允许您在一分钟内开始编写复杂的测试用例。
• 它为您做了大量工作
  • 使用一条命令下载并安装 Selenium 服务器
  • 设置您选择的浏览器
  • 在失败的断言上自动截图
  • 以 JUnit 格式生成测试结果（易于处理，例如 Jenkins 和其他工具）
  • 等等...
• 测试并行运行，因此唯一的瓶颈是同时启动的 Selenium 节点数量。
• 简单的语法糖层在默认的 WebDriver 命令 之上，有助于缩短您的测试并提高可读性。
• 如果您已经使用 PHP，您不需要学习新语言来编写功能测试。此外，如果您熟悉单元测试和 PHPUnit，您就知道了。
• 允许您规划测试依赖关系。
  • 例如，如果您需要在测试结果之前等待 2 分钟直到某个事件通过您的消息队列？没问题！测试的顺序被优化以最小化总执行时间。
• 在测试执行期间可以清楚地查看测试状态，因此您将很容易知道已经完成了多少测试以及它们的结果。
• 您可以通过向 EventDispatcher 注册自定义事件来轻松扩展 Steward。
  • 例如，您可以添加自定义配置选项或更改传递给子 PHPUnit 进程的参数。
• 云服务如 Sauce Labs、BrowserStack 或 TestingBot 完全集成，让您有机会在不设置自己的基础设施的情况下运行测试。
• 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文件

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

6. 查看测试执行时间线

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

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

./vendor/bin/steward generate-timeline

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

许可证

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