When initially building out a testing framework for an application, you have a wealth of tools, plug-ins, and approaches to choose from. What tool works best for the application you are developing? How should you structure the tests or organize any UI elements? And, as your test suite grows, you may find yourself asking where tests should run. Running locally may work well for a small suite of tests or if a project is just spinning up, but as the application (and development process) matures, it becomes necessary to scale the test framework too.
Running tests locally – like Protractor tests – isn’t very useful if you want to incorporate them with your team’s build process. It also doesn’t contribute much to the idea of knowledge sharing with your team. Incorporating tests with builds can help your team discover issues early on before a major release. Also, having a central location to kick off tests gives greater flexibility in who can run a suite and when the suite can be run. This is where Continuous Integration comes in and integrating your Protractor tests with a CI server is relatively simple.
Let’s take a look at how to set up your Protractor suite of tests with one of these CI platforms: CircleCI – where all it takes to run your tests is a few lines in your project’s circle.yaml. Before we get to the good stuff, though, let’s discuss a few setup steps needed to make the transition from running tests locally to running on CircleCI.
First Things First
First and foremost, don’t forget to have Circle checkout your project from GitHub and install all of your app’s dependencies. We won’t discuss those steps here, but Circle has extensive documentation on how to get started with its platform. The final step of the setup process is configuring a test database for your Protractor tests.
Don’t Forget Your Data
Circle has the more popular databases already installed and available for your project so simply add lines similar to the following to circle.yaml to set up your project’s database:
## Database setup
database:
override:
— mysql -u ubuntu circle_test < my-database-setup.sql
The command may differ slightly based on the database you use.
Run Your Tests
After setting up your database and including all of the necessary dependencies in Circle’s configuration file, add the following lines to run your tests:
## Run All The Tests!
test:
override:
— folder/to/protractor — suite suite1
And that’s it! Running your tests in Circle is as simple as adding your test commands to circle.yaml.
Troubleshooting Test Failures
You can open up the testing build step in Circle and see the console output of your tests, but that’s about it starting out. Thankfully, we have the ability to include reports with our suite as build artifacts. In your Protractor config file, simply replace the base directory of where you store your reports with process.env.CIRCLE_ARTIFACTS. Anything saved in that directory will automatically be created as a build artifact, allowing you to open up the reports as soon as your build finishes.
Another useful feature is the ability to ssh into your CI build. CircleCI make the process easy by offering a tab within each build that helps you ssh into the desired container – utilizing your GitHub credentials. From there, you can watch and manually debug your tests.
Check out the full list of Circle environment variables to see what other options are available for use.
Now What?
If you open up a pull request in GitHub, Circle can automatically run your tests and update you on their status right from the request. If tests pass, you know you’re safe to merge the request. Circle also has test badges you can include in your GitHub project to let your watchers know your code is on point.
Don’t forget to check out the rest of CircleCI’s documentation. They have information about running your tests in parallel, generating build artifacts, and other great How-Tos.
So, what cool things have you done with your project’s integration with Circle? How have you implemented your Protractor test suite to best utilize Circle’s features?
