In my last blog post, I explained why low code development platforms like Appian need to have a CI / CD environment that includes automated testing and deployments. Implementing a test framework like Cucumber is an essential first step any organization can take to increase the number of reliable deployments.
This blog covers what Cucumber is, how it works, how to set it up, and a brief description of how developers, business analysts, and stakeholders alike can write test cases against an Appian Cloud environment. We aren’t going to cover how to test against local docker environments since these environments require a significant amount of setup and configuration.
Cucumber: A Primer
Cucumber is a widely used front end behavior driven development testing framework that enables business users and developers to collaborate using a common language. It’s open-source and has been used within the Java community for years. The gherkin syntax (Given, When, and Then) allows non technical users to implement test scripts and contribute to the development process. Even further, technical users can extend what Appian has already developed and create custom steps that Appian designers and developers can use.
To get started with this tutorial, you will need to make sure the following tools are installed and configured properly:
- A desktop/laptop computer
- An Appian Community Account
- Java JDK (8 or greater)
- Java JRE
- An IDE such as IntelliJ
Create Test Users
It is a best practice to have dedicated test users created within Appian based on the roles you are testing. Most Appian end-users are set up as basic users so they can only see relevant and contextual data in enterprise environments. However, Appian Designers usually have system administrator privileges, so permissions errors and similar misconfigurations can be missed if we don’t test using roles that have limited permissions.
1. Login to your Appian Environment and head over to the admin console
2. Click on the Users tab on the left-hand side
3. Click the Create button and you will see the user window pop up
4. Fill in the form as required
5. For the username, it’s AVIO’s recommendation to add a prefix, like “cucumber”, to the username so other designers know that the user is only for test purposes
6. If your application requires it, add the user to the expected group by selecting the group from the application and clicking ‘add members’
7. Open up a private/incognito browsing window and login with that user and change the password to a permanent one. A separate private browser window ensures that you can login to both a standard admin account and the new user’s account at the same time
8. Repeat this process until all test users are added
1. Click on this Appian AppMarket Link to download the Sample Project
2. Click the download button on the top right (If you aren’t signed in you’ll see a ‘schedule demo’ button, click the person icon on the top right part of the page header to sign in
3. Unzip the project into your workspace directory
4. Open up IntelliJ (or your preferred IDE) and import the project
5. You’ll notice that there is a sub-folder when importing the project, click on that sub folder, then click OK
6. When Prompted, click import project from external module > Maven
7. On the next Page, click Import Maven Projects Automatically, and Automatically download sources and documentation
8. Click Next all the way through and let Maven install the needed dependencies to your computer
9. Now you’re at a blank screen with a folder view on the left hand side, expand out the folders so it looks like the screenshot below
10. Open the users.properties files
11. Add in the usernames and passwords that you created in the appian environment in the same format that was there (username=password)
12. To make it easier when writing tests, we can specify the role we are testing instead of a username. The user we created earlier has a role of sales associate, so I’m going to add that in as well. The format is role.roleName=username|password
13. If you are a windows user, you can skip this part. Otherwise, open the custom.properties file
- Expand lib/drivers
- Right-click on the driver for your OS and click 'Copy Path'
- Paste the chrome.driver path in chrome.driver.home
14. Now open up src/test/java/TestRunner/RunCucumberForAppianTest
15. Remove the ‘@Tempo and’ piece of text. This will allow you to run tests that have the ‘@Application’ Tag
Now, we are ready to write our first test case. Optionally, and for the best experience, you will want to install the Cucumber for Java Plugin from the Jetbrains Marketplace
1. Open up src/test/resources/ApplicationExample.feature
2. Remove the help text
3. Fill in your browser, Appian URL, version number, and locale
4. Remove the last line that says “login with username”
5. Replace that line with “Then I login with role “<insert role you just created>”
- You’ll notice that IntelliJ will pop up with suggestions, you can use
6. Fill in the “<string>” section with the role you created earlier
7. Now we will want to add an actual test. In this example, we are just going to click around Tempo to make sure that this user can access Tempo. Add the following Code after the background scenario.
Scenario: Tempo Works
Then I click on menu "News"
And I click on menu "Tasks"
8. It’s always a good practice to test your feature files regularly to make sure everything works as expected. Do so by pressing ctrl+shift+f10 or right-click on ApplicationExample.feature and click ‘Run’
9. If everything is set up properly, a new window should pop up, login as the user, and open click around the tempo site
- Since most users are going to be using the sites feature, it’s also a good idea to set user start pages and disable tempo access for those users that should be going to a certain site page
Further Testing + Cucumber’s Capabilities
The example above was only a basic example to make sure you can get started with testing. Cucumber is best used when tests are built around acceptance criteria. The possibilities are endless. In the example below, the selectable grid is tested pretty thoroughly every time tests are run. When developing and testing, AVIO recommends creating test cases for any errors encountered, thereby ensuring all bases are covered when it comes to deployment time. The best thing to do to get better at writing cucumber tests is constantly reviewing the cheat sheet and using the auto-complete feature in IntelliJ.
You can further extend Cucumber by adding in your own step definitions in conjunction with Appian’s as we have done. We have found several instances where we needed to build our own step definitions to write more robust tests.
Using Maven, Docker, and Selenium’s ChromeDriver, we’ve also leveraged headless and parallel testing. Parallel testing allows us to significantly reduce testing time compared to running all tests sequentially, and by going headless, we do not need to have a browser window open, which frees up developers to work on other things while tests are running.
Feel free to contact us if you have any questions about using Cucumber with Appian, or any other questions about automated testing and CI / CD pipelines. Our next blog series will cover how to automate the cucumber tests we just created in Jenkins.