{"id":14978806,"url":"https://github.com/lmc-eu/steward","last_synced_at":"2025-05-16T13:07:51.183Z","repository":{"id":31738633,"uuid":"35304655","full_name":"lmc-eu/steward","owner":"lmc-eu","description":"PHP libraries that makes Selenium WebDriver + PHPUnit functional testing easy and robust","archived":false,"fork":false,"pushed_at":"2024-08-16T10:07:10.000Z","size":1521,"stargazers_count":221,"open_issues_count":19,"forks_count":39,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-02T06:18:30.567Z","etag":null,"topics":["php","php-webdriver","phpunit","selenium","selenium-webdriver","webdriver"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lmc-eu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-08T22:23:47.000Z","updated_at":"2025-03-22T08:45:37.000Z","dependencies_parsed_at":"2023-02-10T22:15:31.733Z","dependency_job_id":"0528c2ae-b5b4-48a4-9043-e10e5f8c2112","html_url":"https://github.com/lmc-eu/steward","commit_stats":{"total_commits":655,"total_committers":18,"mean_commits":"36.388888888888886","dds":0.08091603053435115,"last_synced_commit":"03cdb6b742a9124df8e5854ef587a59727deaf02"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fsteward","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fsteward/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fsteward/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lmc-eu%2Fsteward/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lmc-eu","download_url":"https://codeload.github.com/lmc-eu/steward/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247999859,"owners_count":21031046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","php-webdriver","phpunit","selenium","selenium-webdriver","webdriver"],"created_at":"2024-09-24T13:58:26.535Z","updated_at":"2025-04-09T08:06:34.881Z","avatar_url":"https://github.com/lmc-eu.png","language":"PHP","readme":"# Steward: easy and robust testing with Selenium WebDriver + PHPUnit\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/lmc/steward.svg?style=flat-square)](https://packagist.org/packages/lmc/steward)\n[![GitHub Actions Build Status](https://img.shields.io/github/actions/workflow/status/lmc-eu/steward/tests.yaml?style=flat-square\u0026label=GitHub%20Actions%20build)](https://github.com/lmc-eu/steward/actions)\n[![AppVeyor Build Status](https://img.shields.io/appveyor/ci/lmc-eu/steward/main.svg?style=flat-square\u0026label=AppVeyor)](https://ci.appveyor.com/project/lmc-eu/steward)\n[![Coverage Status](https://img.shields.io/coveralls/lmc-eu/steward/main.svg?style=flat-square)](https://coveralls.io/r/lmc-eu/steward?branch=main)\n[![Total Downloads](https://img.shields.io/packagist/dt/lmc/steward.svg?style=flat-square)](https://packagist.org/packages/lmc/steward)\n\nSteward is a set of libraries made to simplify writing and running robust functional system tests in\n[PHPUnit](https://phpunit.de/) using [Selenium WebDriver](https://www.selenium.dev/).\n\n## What's great about Steward?\n- It allows you to start writing complex test cases in a minute.\n- It performs a lot of work for you:\n   - downloads and installs Selenium server with one command\n   - sets-up browser of your choice\n   - automatically takes a screenshot on failed assertions\n   - produces test results in JUnit format (easily processable, for example, by Jenkins and other tools)\n   - and more...\n- Tests are run in parallel, so the only bottleneck is the number of Selenium nodes you start simultaneously.\n- Simple syntax sugar layer on top of default [WebDriver commands](https://github.com/php-webdriver/php-webdriver/wiki/Example-command-reference) helps shorten your tests and improve readability.\n- If you already use PHP, you don't have to learn a new language to write functional tests. Moreover, if you are familiar with unit tests and PHPUnit, you know it all.\n- Allows you to plan test dependencies.\n   - For example, if you need to wait 2 minutes until some event gets through your message queue before testing the result? No problem! The order of tests is optimized to minimize the total execution time.\n- Status of tests can be clearly watched during test execution, so you will easily know how many tests have finished and what their results are.\n- You can extend Steward easily by registering custom events to EventDispatcher.\n   - For example if you can add custom configuration options or change parameters passed to child PHPUnit processes.\n- Cloud services like [Sauce Labs](https://saucelabs.com/), [BrowserStack](https://www.browserstack.com/) or [TestingBot](https://testingbot.com/) are fully integrated giving you a chance to run tests with less setup and without your own infrastructure.\n- Steward is field tested - we use it daily in [our company](https://www.lmc.eu/en/) to maintain the quality of our products thanks to hundreds of test-cases. The library itself is also extensively covered by unit tests.\n- Steward is built on solid foundations: [WebDriver](https://www.w3.org/TR/webdriver/) is W3C draft standard for browser automation,\n[php-webdriver](https://github.com/php-webdriver/php-webdriver) is the most used and developed Selenium language binding for PHP,\n[PHPUnit](https://phpunit.de/) is a well known and widely used testing framework, and\n[Symfony Console](https://symfony.com/doc/current/components/console.html) is industry standard for PHP CLI applications.\n\n## Example usage\nTo see how to use and extend Steward, have a look at our [example project](https://github.com/lmc-eu/steward-example).\n\n## Changelog\nFor the latest changes see the [CHANGELOG.md](./CHANGELOG.md) file. We follow [Semantic Versioning](https://semver.org/).\n\n## Getting started\n### 1. Install Steward\nFor most cases we recommend having functional tests in the same repository as your application but in a separate folder.\nWe suggest putting them in a `selenium-tests/` directory.\n\n**In this directory**, simply install Steward with the following command:\n\n```sh\n$ composer require lmc/steward\n```\n\n**Note:** you will need to have [Composer](https://getcomposer.org/) installed to do this.\n\n### 2. Download Selenium Server and browser drivers\nThe following step only applies if you want to download and run Selenium Standalone Server with the test browser locally right on your computer.\nAnother possibility is to [start Selenium Server and test browser inside a Docker container][wiki-docker].\n\n#### Get Selenium Standalone Server\nYou need to download Selenium server so it can execute commands in the specified browser.\nIn the root directory of your tests (e.g. `selenium-tests/`)  simply run:\n\n```sh\n$ ./vendor/bin/steward install\n```\n\nThis will check for the latest version of Selenium Standalone Server and download it for you (the jar file will\nbe placed into the `./vendor/bin` directory).\n\nYou may want to run this command as part of your CI server build, then simply use the `--no-interaction` option to\ndownload Selenium without any interaction and print the absolute path to the jar file as the sole output.\n\n#### Download browser drivers\nIf it is not already installed on your system, you will need to download Selenium driver for the browser(s) you want to\nuse for the tests. See [Selenium server \u0026 browser drivers][wiki-drivers]\nin our wiki for more information.\n\n### 3. Write the first test\nTo provide you with Steward functionality, your tests have to extend the `Lmc\\Steward\\Test\\AbstractTestCase` class.\n\nYou must also configure [PSR-4 autoloading](https://www.php-fig.org/psr/psr-4/) so that your tests could be found by\nSteward. It is as easy as adding the following to your `composer.json` file:\n\n```json\n    \"autoload\": {\n        \"psr-4\": {\n            \"My\\\\\": \"tests/\"\n        }\n    }\n```\nDon't forget to create the `selenium-tests/tests/` directory and to run `composer dump-autoload` afterward.\n\nFor the test itself, place it in the `selenium-tests/tests/` directory:\n\n```php\n\u003c?php\n// selenium-tests/tests/TitlePageTest.php\n\nnamespace My; // Note the \"My\" namespace maps to the \"tests\" folder, as defined in the autoload part of `composer.json`.\n\nuse Facebook\\WebDriver\\WebDriverBy;\nuse Lmc\\Steward\\Test\\AbstractTestCase;\n\nclass TitlePageTest extends AbstractTestCase\n{\n    public function testShouldContainSearchInput()\n    {\n        // Load the URL (will wait until page is loaded)\n        $this-\u003ewd-\u003eget('https://www.w3.org/'); // $this-\u003ewd holds instance of \\RemoteWebDriver\n\n        // Do some assertion\n        $this-\u003eassertContains('W3C', $this-\u003ewd-\u003egetTitle());\n\n        // You can use $this-\u003elog(), $this-\u003ewarn() or $this-\u003edebug() with sprintf-like syntax\n        $this-\u003elog('Current page \"%s\" has title \"%s\"', $this-\u003ewd-\u003egetCurrentURL(), $this-\u003ewd-\u003egetTitle());\n\n        // Make sure search input is present\n        $searchInput = $this-\u003ewd-\u003efindElement(WebDriverBy::cssSelector('#search-form input'));\n        // Or you can use syntax sugar provided by Steward (this is equivalent of previous line)\n        $searchInput = $this-\u003efindByCss('#search-form input');\n\n        // Assert title of the search input\n        $this-\u003eassertEquals('Search', $searchInput-\u003egetAttribute('title'));\n    }\n}\n\n```\n\n### 4. Run your tests\n#### Start Selenium server\nNow you need to start Selenium server, which will listen for and execute commands sent from your tests.\n\n```sh\n$ java -jar ./vendor/bin/selenium-server-4.10.0.jar standalone # the version may differ\n```\n\nThis will start a single Selenium Server instance (listening on port 4444) in standalone (alias \"no-grid\") mode\n(meaning the server will receive and execute the commands itself, without distributing to nodes).\n\n**Note:** You may want to run Selenium  Server in a grid mode. This has the *hub* receiving commands while multiple *nodes* execute them.\nSee [Selenium Grid](https://www.selenium.dev/documentation/grid/getting_started/#hub-and-node) documentation.\n\n#### Run Steward!\nNow that Selenium Server is listening, let's launch your test! Use the  `run` command:\n\n```sh\n./vendor/bin/steward run staging firefox\n```\n\nIn a few moments you should see a Firefox window appear, then the https://www.w3.org/ site (as defined in the example tests)\nshould be loaded before the window instantly closes. See the output of the command to check the test result.\n\nThe `run` command has two required arguments: the name of the environment and the browser:\n- The environment argument has no effect by default, but is accessible in your tests making it easy to, for example, change the base URL of your tested site. This would be useful for testing between your local server and staging environments\n- The browser name could be any browser name supported by Selenium. Most common are \"firefox\", \"chrome\", \"phantomjs\", \"safari\" and \"internet explorer\". See our wiki for more info related to [installing browser drivers][wiki-drivers].\n\nThere is also a bunch of useful options for the `run` command:\n\n- `--group` - only run specific group(s) of tests\n- `--exclude-group` - exclude some group(s) of tests (can be even combined with `--group`)\n- `--server-url` - set different url of selenium server than the default (which is `http://localhost:4444`)\n- `--xdebug` - start Xdebug debugger on your tests. Allows you to debug tests from your IDE ([learn more about tests debugging][wiki-debugging] in our Wiki)\n- `--capability` - directly pass any extra capability to the Selenium WebDriver server ([see wiki][wiki-capabilities] for more information and examples)\n- `--parallel-limit` - limit number of testcases being executed in a parallel (default is 50)\n- `--help` - see all other options and default values\n- **adjust output levels:** by default, only the test results summary is printed to the output; the verbosity could be changed by the following:\n    - `-v` - to instantly output name of failed test(s)\n    - `-vv` - also print progress information during run (which tests were started/finished etc); if any test fails, its output will by printed to the console\n    - `-vvv` - output everything, including all output from the tests\n\n### 5. See the results and screenshots\nThe log is printed to the console where you run the `run` command. This could be a bit confusing, especially if you run multiple tests in parallel.\n\nAs a solution, for each testcase there is a separate file in JUnit XML format, placed in `logs/` directory. Screenshots and HTML snapshots are also saved into this directory (they are automatically generated on failed assertion or if a WebDriver command fails).\n\nTo see the current status of tests during (or after) test execution, open the `logs/results.xml` file in your browser:\n\n![Example output as displayed in logs/results.xml file](https://lmc-eu.github.io/steward/images/results-output-example.png)\n\nSimilar output in the command line interface can be obtained using the `./vendor/bin/steward results` command (see below). You can also add `-vvv` to see results of each individual test.\n\n![Example output of results command](https://lmc-eu.github.io/steward/images/results-output-cli.png)\n\n### 6. See test execution timeline\nSteward provides a visual representation of the test execution timeline. When used with Selenium Server in \"grid\" mode you can see which\nSelenium node executed which testcase, identify possible bottlenecks and so on.\n\nTo generate the timeline, simply run the `generate-timeline` command after your test build is finished:\n\n```sh\n./vendor/bin/steward generate-timeline\n```\n\nFile `timeline.html` will then be generated into the `logs/` directory.\n\n![Example timeline visualization](https://lmc-eu.github.io/steward/images/timeline.png)\n\n## License\nSteward is open source software licensed under the [MIT license](./LICENSE.md).\n\n[wiki-docker]: https://github.com/lmc-eu/steward/wiki/Selenium-server-\u0026-browser-drivers#option-2-start-selenium-server--browser-inside-docker-\n[wiki-debugging]: https://github.com/lmc-eu/steward/wiki/Debugging-Selenium-tests-with-Steward\n[wiki-capabilities]: https://github.com/lmc-eu/steward/wiki/Set-custom-capabilities\n[wiki-drivers]: https://github.com/lmc-eu/steward/wiki/Selenium-server-\u0026-browser-drivers#2-install-browser-driver\n","funding_links":[],"categories":["Resources"],"sub_categories":["Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmc-eu%2Fsteward","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flmc-eu%2Fsteward","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flmc-eu%2Fsteward/lists"}