We received a lot of requests from our users to help them to integrate Appium with Hiptest. For those who don't know it, Appium is a test automation framework used for mobile testing and designed to work with any types of mobile application (native, web or hybrid, on iOs or Android) and compatible with multiple languages and test frameworks.
Because its philosophy, we couldn't have provided a simple Appium export built in the hiptest-publisher, so that's why we've decided to write this post to help you to setup your technical environment, based on the same model than our previous post about Calabash integration. As for this last post, we are going to write an acceptance test for the Android Wikipedia application, and automate it with Ruby and the RSpec framework.
Before all, you will need:
- A Hiptest account
- The hiptest-publisher
- The apk of your app (you can find Wikipedia's with a few searches, given it's free and open source)
- A proper installed Android SDK and a working and running virtual device
- A Ruby install (with Bundle)
- And of course, Appium (check the install process at the bottom of this page)
Setup your project
Create a new directory and move your apk file in it. Then, create a Gemfile and add these gems:
Run "bundle install" in the directory and it's done.
The Appium console (or Arc) allows you to drive a device (virtual or not) by using the Ruby Appium library API. We are going to use it to experiment instructions that will be later part of our automation scripts.
After running Bundle, create a file named "appium.txt" in your directory. Open it and fill it with this content:
platformName = "Android"
deviceName = "Android Emulator"
app = "/path/to/your_app.apk"
appActivity = ".myMainActivity"
appPackage = "my.app.package"
Now, launch your virtual device with the Android emulator and an Appium server (simply type the command line "appium"), then run the "arc" command. The apk will be installed on the virtual device and launched, and a Ruby prompt will be displayed, ready to receive your orders :)
Now, run "rspec --init" from the command line to create the basic files used to run your RSpec test suite. A file named "spec_helper.rb" will be created. Fill it like this:
RSpec.configure do |config|
appium_txt = File.join(Dir.pwd, 'appium.txt')
caps = Appium.load_appium_txt file: appium_txt
@driver = Appium::Driver.new(caps).start_driver
@driver.manage.timeouts.implicit_wait = 30
@wait = Selenium::WebDriver::Wait.new :timeout => 30
We will run the test execution with the same Appium capabilities (you can find the whole list here) than for the console, but nothing prevents you to use another configuration. Also, we create here an instance of the Appium driver and an instance of the wait object, to have more control on the elements displayed on the screen.
Now that the setup is done, we are ready to write our test!
Write and automate your test scripts with Hiptest
Write the test
We are going to validate the History feature of the Wikipedia mobile app. First, log in to Hiptest, create a new project and create a new scenario. Then, just write your test steps:
As you can see, the scenario is written using the Gherkin syntax for a better readibility. If you want to do so, activate the BDD mode in the project settings.
Get the executable script
Go to the automation panel of your project, head to the "Publish your tests with Hiptest-Publisher" section and get your Ruby/RSpec config file:
Move the "hiptest-publisher.config" file into your directory, then run:
hiptest-publisher --config hiptest-publisher.config --output-directory spec
You'll get three files, but only two interested us here: "project_spec.rb" and "actionwords.rb". If you open the first one, you'll see your scenario converted into a RSpec test case. Its definition is only constituted of methods calls that match the scenario steps. Actually, you won't ever need to modify this file.
To automate the execution of the test, we are going to implement the steps defined as Ruby methods in the actionwords.rb file.
- Brace yourself, you are going to assist to an unique and totally mastered transition to the next part-
Let's open this file and...
Use the Appium Ruby library to automate the script
That's where we are going to give instructions to Appium to make it interact with our app and write the assertions that will leave us sure that everything is working as well as expected.
I picked Wikipedia app also because it's a hybrid app, which means that some parts are coded in the native Android language (widget like the search bar) and others are simple web views displayed in a container (basically, the articles pages).
Appium provides the notion of contexts to make you able to interact with the both kinds of GUI components. All you have to do is to switch between those contexts depending of with which one you want to interact or make assertion on.
To list the contexts of your app, launch the Appium console and run "available_contexts":
 pry(main)> available_contexts
You can then switch from one context to another with "set_context":
# switch to native context
 pry(main)> set_context "NATIVE_APP"
# switch to webview context
 pry(main)> set_context "WEBVIEW_org.wikipedia"
Based on this, I wrote two test helpers to easily switch between the two contexts during automation process:
(Don't forget to include this module in your RSpec config)
A first step automation
Let's have a glance to the first step of our scenario, "app_opened_as_unregistered_user". I just want to be sure that the app is opened and display the Home page (the "Today's featured article").
Wikipedia Home Page
Appium library provides a "find" method that can find widgets in the GUI of your app. So we are going to check if the title "Today's featured article" appeared when we open the app to automate the first step of the scenario. To inspect a Webview, use Google Chrome and its devices inspector feature (look there).
# we are checking something in the webview
h2s = find_elements :tag_name, "h2"
expect(h2s.first.text).to eq "Today's featured article"
Run your Rspec suite. The test should succeed.
You just automated your first step written in Hiptest with Appium!
You can repeat this process to implement the remaining steps. Here is the complete actionwords script available for download.
We just saw here a basic setup of an automated test execution with Appium. You will surely execute your tests on multiple platforms at the same time to ensure that their app is working on every device. To do that, some tools exist like SauceLabs (who sponsors Appium) or TestObject.