A Selenium framework that implements the Page Object Model (POM) using Object Oriented Programming (OOP) concepts. It abstracts out most of the complexity of Selenium to allow users to focus on automating tests and not spend time dealing with the technical details of implementing an automation framework, so that automated tests can be written in a non-technical way in the same amount of time as manual tests can be executed.
If you want to write tests, you are in the wrong place. Head over to the sentinel.example Project to get started. There is extensive documentation there along with sample code to get you up and running in minutes. You can also check out the Sentinel Javadocs, especially the steps package. Sentinel is intended to be included in your test automation and used as a jar file. If you are writing tests, you should NOT be modifying the Sentinel code itself.
People wondering where they can write glue code @Given, @When, and @Then steps should first be asking what has been written and attempting to reuse that instead of writing their own. If you are writing your own more than 1% of the time then you are not using the framework as intended and wasting time (or working on something really weird).
These instructions will get you a copy of the project up and running on your local machine for development purposes. See deployment for notes on how to deploy the project to Maven Central.
What things you need to install the software and how to install them:
- Java (11 or later)
- Maven (2.5.4 or later)
- Integrated Development Environment (Eclipse Suggested)
- Google Chrome (suggested)
These instructions assume you are using Eclipse.
On the command line: Clone the project from git.
git clone https://github.com/dougnoel/sentinel.git
- Open Eclipse
- File -> Open Projects from File system...
- Next to Import Source click the Directory button and browse to the installed location.
- Click the Finish button.
- Right-Click on the project in the Project Explorer.
- Maven -> Update Project...
- Wait for the status bar in the lower right-hand corner to finish before continuing.
On the command line type: mvn test.
In Eclipse:
- Expand src/test/java/ -> tests
- Right-click on SentinelTests.java and select Run As... -> JUnit Test
All of this is explained at length in the sentinel.example Project project. If you want to use this framework to write tests, that is the code you need to check out - not this. You check this code out to contribute to the project.
This script will run code coverage and then open up the results in your default browser. The results will not open if there are build failures.
src/test/resources/scripts/UnitTests.sh
Press CTRL + Click (Command + Click on a Mac) on the feature file scenario, This should navigate to associated step defintion, but if this does not work, the follow below steps:
- In Eclipse go to Help
- Select Eclipse Marketplace
- Search for cucumber
- result should return Cucumber eclipse plugin and Natural plugin
- If none of them are installed then install only Cucumber eclipse plugin
- If both are installed then uninstall Natural plugin and keep Cucumber plugin installed
- After install the plugin, Right click on the Project --> Configure --> Convert to Cucumber project
- Open any feature file: Right click on feature file and select cucumber editor
- Now CTRL + Click (Command + Click) should navigate to the step definition file. Enjoy coding :)
Add additional notes about how to deploy this on a live system in Bamboo/Jenkins/etc.
To build a file for release, open up the pom.xml and change the version number using Semantic Versioning to the next release number. Alternately an X.X.X-SNAPSHOT version can be created.
Then just run:
mvn package
The jar file will be located in the target directory.
To install it locally:
mvn install:install-file -Dfile=sentinel-1.0.0-SNAPSHOT.jar -DgroupId=com.dougnoel -DartifactId=sentinel -Dversion=1.0.0-SNAPSHOT -Dpackaging=jar -DgeneratePom=true
If you want to do this all in one step without generating a jar, just run:
mvn install
If you want to deploy a snapshot version for use by people, use:
mvn deploy
As long as you are setup to deploy to Maven central (see Section 5.3 below), to use the version, all someone will need to do is change their version to the SNAPSHOT version and have the following in their settings.xml:
<repositories>
<repository>
<id>oss.sonatype.org-snapshot</id>
<url>http://oss.sonatype.org/content/repositories/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
Instructions for Deploying to Maven Central Here is an article on encrypting the PGP password in settings.xml. This git project also shows an example of how to push to Maven Central.
Had to run export GPG_TTY=$(tty) per this article on using GPG on Mac for this all to work.
(NOTE: The version needs to be X.X.X-SNAPSHOT for a release to work.)
When release:prepare and release:peform run, they pull command line arguments from the maven-release-plugin section of the pom.xml. These are in turn set in the properties section of the pom.xml under sentinel-release-os, sentinel-release-browser, and sentinel-release-pageobjectpackages at the top of the file. If you need to change these properties, change them here. If you need to add additional arguments, add them to the arguments section and follow the standard for adding the property values to the properties section of the file.
mvn clean
mvn release:prepare
mvn release:perform
After deployment, follow the Sonatype Instructions for releasing a deployment.
To create a GPG Key, you need a tool. The following tool for Mac has a UI https://gpgtools.org/. When creating a key, you must use the Advanced Settings and follow the instructions above.
Sentinel comes with Javadocs which describe its classes in great detail. This includes examples of how you can use the generic Cucumber steps that are already included. The Sentinel Javadocs are updated on github with every new version.
The Javadocs can also be easily generated by running the following command.
mvn javadoc:javadoc
The files are generated in the docs folder and can be accessed by opening up the index.html file contained within that folder.
Every method should have a Javadoc comment describing what it does, its parameters, what it returns (if not void), and any exceptions it throws. We follow the Liferay-Portal Javadoc Guidelines for writing Javadoc contents.
- Make sure you have updated the version in the pomfile if necessary (pom.xml)
- Run
mvn javadoc:javadoc - Commit the changes and merge them with main. The files will be pulled from the docs folder and published on https://dougnoel.github.io/sentinel/
For more information, refer to Configuring a publishing source for your GitHub Pages site Additional information can be found under About GitHub Pages and Jekyll and the GitHub Pages site.
4.2 Changelog
The changelog is generated using github_changelog_generator.
github_changelog_generator -u dougnoel -p sentinel --token
- Apache Commons CSV - CSV reading/writing library
- Apache PDFBox - PDF reading/writing library.
- Apache StringUtils - Advanced String functionality that is optimized.
- Appium - Automation for Application Platforms outside of the Web, used for WinAppDriver.
- Cucumber - BDD Testing Framework
- Cucumber Extent Reporter 7 Interface between Cucumber Results and Extent Reports.
- Commons Lang - Apache Commons Lang 3 for common Java language options
- Extent Reports - A report framework for automation testing.
- HttpComponents - Apache HttpComponents for API testing.
- Image Comparison - Library for comparing screenshots for screenshot testing.
- Jackson - Libraries for reading YAML, JSON and other config files.
- Log4j2 - Apache logging framework.
- PDFBox - Apache library for reading PDF files.
- Maven - Apache dependency management.
- Maven Javadoc Plugin - Plugin to allow maven to generate Javadocs.
- Monte Screen Recorder - Library for recording video of executions.
- Saucelabs - Multi-Platform, multi-browser external testing service.
- Selenium - The automation framework workhorse.
- Swagger Parser - Reads Swagger API files, allowing us to use them as API Objects.
- Traprange - Independent library developed using PDFBox to deal with tables in PDFs.
- Unirest - A simple API library used for the API testing functionality.
- WebDriverManager 4.4.1 - Automatically detects browser versions and downloads the correct drivers.
- WinAppDriver - Microsoft maintained library for automating Windows OS.
All web drivers are managed by WebDriverManager. Both the operating system and browser are automatically detected and the appropriate web driver is downloaded. Downloaded drivers are cached on individual boxes. The following browsers are supported:
- Chrome (Chromedriver)
- Edge (Edgedriver)
- Firefox (Geckodriver)
- Internet Explorer (IE Driver)
- Opera (OperaChromiumDriver)
- Safari (Safaridriver)
Sentinel is setup to use Saucelabs for remote execution. This is the recommended way to execute test in your build pipeline, because you then do not need to setup an execution server.
We use Semantic Versioning for versioning. For the versions available, see the tags on this repository.
- Doug Noël - Architect - Initial Work
- Sam Pacos - Developer - IFrame Automatic Handling, Tables, Additional Contributions
- Paul Turchinetz - Developer - Expanded Cucumber Steps, Dynamic Loading of Elements, Additional Contributions
- Tyler Bouchard - Contributor - Windows Automation, Tables, Additional Contributions
- Peter Krzywicki - Contributor - Minor Updates
This project is licensed under the Apache Commons 2.0 License - see the LICENSE.md file for details
- Some design choices inspired by Cheezy's Page Object gem.