Tracks Automating and Testing Case Study

Support page for - Automating and Testing a REST API.

Tools etc.

• 20190225 - added a video showing how to install tracks via Docker and run the code
• 20180412 - added a video showing how to install and use the source code for the book
• 20180409 - amended the code for Java 1.9 - had to update to version 3.0.7 and add some additional maven dependencies in the pom.xml
• 20180324 - added videos showing how to install cURL on windows
• 20180323 - added video showing how to install the Turnkey Tracks VM into Virtual Box
• 20170909 - added text description of the steps I used to run from Turnkey VM
• 20170804 - update, Bitnami have discontinued their VM and workaround for Turnkey Icon isses

Tracks

Tracks is an open source application written in Ruby on Rails which implements the David Allen “Getting Things Done” time management methodology.

• Tracks Home Page - getontracks.org
• Getting Things Done

Tracks Installers

My current recommended approach is to use Docker,

• docker instructions (see video below)
• getontracks.org/downloads aboutbitnamitracks
• Bitnami Tracks Installer

Virtual Machine Software

• vmware.com
• virtualbox.org

Prebuild Tracks Virtual Machines

• Turnkey Tracks
• Bitnami Tracks
  • if you are experiencing issues with GUI icons then see this workaround

cURL

You can install cURL on windows using:

• one click installer from http://www.confusedbycode.com/curl/
• chocolatey using choco install curl https://chocolatey.org/
• the official site https://curl.haxx.se/ (use the download wizard https://curl.haxx.se/dlwiz/)

see the videos below for each of these installation approaches

HTTP Proxies

The easiest HTTP Proxies to use are:

• For Windows: Fiddler
• For Mac: Charles

You could also use:

• Zed Attack Proxy
• BurpSuite Free Edition

REST

You can find information about REST:

• REST Wikipedia page
• An overview REST tutorial at restapitutorial.com
• Roy Fielding defined REST in his Ph.D. Thesis, you can read it as a .pdf

REST API Tools

• cURL official page
• Postman REST GUI Client getpostman.com

Tools not used in the case study:

• Insomnia.rest cross platform desktop REST client

REST Java API Libraries

The case study uses REST-assured:

• REST-assured

Other libraries are available:

• unirest
• resty
• jersey
• JavaLite
• OkHTTP
• Apache HttpClient

Lists of APIs to Experiment With

Fake APIs - i.e. these are api endpoints which serve canned data and responses

• https://jsonplaceholder.typicode.com/
• https://fakerestapi.azurewebsites.net/
• https://reqres.in/
• https://www.onlinetool.in/fake-rest-api
• https://swapi.dev/ - (GET requests only)

Lists of APIs (primarily of use to see different api styles and approaches)

• https://any-api.com/
• https://github.com/toddmotto/public-apis/blob/master/README.md

APIs designed for testing against

• https://gorest.co.in/
• https://httpbin.org/
• https://apichallenges.herokuapp.com/
• https://restful-booker.herokuapp.com/
• https://github.com/eviltester/thingifier
• https://github.com/eviltester/TestingApp/releases

Source

The source code for all the Java code used to automate Tracks as part of the case study is available on Github

• github.com/eviltester/tracksrestcasestudy

There is a video below showing how to install and use the source code.

Postman Collection

The Postman Collection for the case study is available in the above source code and shared on the Postman site:

• From Github
• From Postman - getpostman.com/collections/b9e81b009bfd21ec5e83
• As a bit.ly - bit.ly/2iPaxgj

Videos

I created supporting videos for some of the chapters and sections in the book. These make most sense when read in conjunction with the book but offer a visual insight into tools used which the book can’t cover quite as well.

• Installing Tracks using Docker
• Installing Tracks and using a virtual machine
• An overview of Tracks GUI
• Installing cURL for Windows
• An overview of REST interaction with CURL
• Using HTTP Debug Proxies as part of your REST testing
• Using HTTP Debug Proxies with Docker and Localhost
• Using HTTP Debug Proxies as Fuzzers to Create Data
• An overview of the Postman GUI client
• Using Postman GUI Client with an HTTP Proxy
• Installing and Using the Java Source Code

Installing Tracks Via Docker

This is easy to install using Docker and this video shows the process in action.

• You need to setup a Docker account at https://docker.com
• follow the instructions on the hub page

https://hub.docker.com/r/staannoe/tracks/

docker pull staannoe/tracks
docker run -d --name=tracks -p 80:80 staannoe/tracks

Then visit localhost:80, create an admin account.

• Youtube: youtu.be/BAExBxmlPeY

Installing Tracks Using a Virtual Machine

Installing Tracks to a VM using Turnkey.

The last time I used the Turnkey VM I used the VMWare Player 12 and used the following steps:

• https://www.turnkeylinux.org/tracks
• download the VM (.ova file)
• using vmware workstation 12 player
• “Open a Virtual Machine” - choose the .ova file
• … vmware player spends some time importing the VM…
• run VM
• change password for root and MySql e.g. Pa55Word
• skip hub and password setup
• skup security updates
• change VM to use HOST-only private network or Bridged Adapter
• select to use DHCP for network config
• note the IP address shown in the dialog e.g. 192.168.222.129
• tracks should be running on this IP address visit http://

Note: The Bitnami install mentioned has been discontinued,read more information here

• Youtube: youtu.be/8rgZOv-yKsY

An overview of Tracks GUI

• Youtube: youtu.be/QK3eK2X4eUA

Installing cURL for Windows

Install cURL using one click installer from confusedbycode.com

Install cURL using chocolatey

Install cURL from official site on Windows

An overview of REST interaction with CURL

• Youtube: youtu.be/XT351ZmeKto

Using HTTP Debug Proxies as part of your REST testing

• Youtube: youtu.be/eAy4Xi3_xM4

Using HTTP Debug Proxies with Docker and Localhost

• Youtube: youtu.be/LjyLOgC3OjM

Using HTTP Debug Proxies as Fuzzers to Create Data

• Youtube: youtu.be/xWpuAtlb1oU

Postman REST GUI Client

An overview of the Postman GUI client

• Youtube: youtu.be/-3d4LapMrVo

Using Postman GUI Client with an HTTP Proxy

• Youtube: youtu.be/yUPg0dh0mow

Installing and Using the Java Source Code

• Youtube: youtu.be/NrDHvu5ewLo

In the video I show:

• Visiting https://github.com/eviltester/tracksrestcasestudy
• Download the .zip file
• Run mvn clean test in the unzipped folder to download the dependencies
• Open the pom.xml in IntelliJ
• Accessing tracks from the VM
• Change the config in TestEnvDefaults
• Running test data setup tests in SetupTracksTestDataUtilityTest
• And I discuss how to can resolve some common setup issues

Related Reading

Other Blog posts and information you might want to read related to the material in the book, I include a lot of extra references in the book, but these were found after publication and I did not want to keep adding more links into the book, so I added them here instead, I also included a few from the book:

Blog Posts and Sites:

• My Basic and Advanced REST API Workshop material this uses a different target application with different code examples.
• Bas Dijkstra’s Open Source API Workshops
• Testing REST Endpoints Using REST Assured by Kostis Kapelonis
• Mark Winteringham has a lot of useful Postman and REST information on his site here are some examples:
  • Postman – Parsing HTML responses
  • Postman – Sharing payloads across requests
  • How to build an automated API Framework part 1 part 2 part 3
  • Also check out Mark’s Github for some apps to test, sample code and REST API presentations
• Danny Dainton’s All Things Postman Github Repo

Book Versions

Ebook

Ebook on sale at leanpub has had the following releases:

• 2017/01/09
  • first release of the ebook
• 2017/07/03
  • second release of the ebook
  • fixed some grammar errors throughout text
  • fixed spelling errors found throughout text
  • added an example in the “cURL Summary” chapter
  • added an introduction chapter “Introduction to APIs” on various web terminology - what is HTTP, what is an API, what is REST, what are HTTP headers, etc.
  • expanded text in “Exploring The Tracks API with cURL through a Proxy”
  • expanded text in chapter “Exploring Tracks API with Postman REST Client”, added info on using with Proxy for Mac
  • added ‘Summary’ to end most chapters
  • split introduction into 3 chapters to allow for the API introduction
  • expanded the cURL case study chapter to have more information on cURL and what it is for, rather than diving straight into the technical stuff
  • added more explanatory notes in the cURL chapter “Case Study Example Using cURL on Tracks”
  • added a new chapter providing an overview of the Tracks 2.3.0 testing before diving into the details “The Case Study Overview - Testing Tracks v 2.3.0”
  • added A new chapter, with a new package in the code, covering JSON and XML processing with REST Assured “REST Assured JSON and XML Processing”
  • expanded the summary chapter on REST Assured “Summary of REST Assured” to cover serializing and deserializing
  • about 50 new pages of material added
• 2017/08/04
  • additional grammar and spelling errors fixed throughout
  • increased dpi of images in readiness for paperback edition
  • split the ‘sample code’ chapter out of the ‘install’ chapter and moved to immediately before the ‘starting to automate’ chapter
  • paperback edition on hold until I amend the install and VM chapter to cater for bitnami discontinued VMs

Paperpack

Paperback edition currently in proof creation and review mode. Will be the same as the 2017/07/03 release.

Bitnami Tracks

On 4th August 2017 I was told that Bitnami had discontinued the Tracks VM and self contained install.

This is unfortunate as I found it the most reliable and easiest way of getting started. Turnkey is now the simplest way of getting started.

I emailed Bitnami, just in case they could reinstate the installs but on 8th August I learned that the installs would not be reinstated. I suspect the following links will forever remain ‘discontinued’.

• Bitnami Tracks
• Bitnami Tracks Installer

You should probably use Turnkey Tracks installers and VMs (but see the additional information below).

Using Bitnami VMs

You can still use Bitnami VMs but you have to install Tracks yourself. The following instructions are the steps I took to install Tracks into the Bitnami Ruby Infrastructure VM.

• https://bitnami.com/stack/ruby
  • download bitnami ruby VM
  • https://bitnami.com/download/files/stacks/rubystack/2.3.4-4/bitnami-rubystack-2.3.4-4-linux-debian-8-x86_64.ova?with_popup_skip_signin=1
• make sure that the VM can access the outside world e.g. curl https://eviltester.com prior to following any steps
  • I switched off my local firewall for 30 mins while doing this (I haven’t added VMWare to my firewall since I changed my local firewall software)
• follow install instructions for tracks
  • https://github.com/TracksApp/tracks/blob/v2.3.0/doc/installation.md
• make a note of the ip address on the start screen 192.168.199.129
  • if you miss the IP Address then when you are logged in you can type the following to show it
    • ip addr show
    • http://www.wikihow.com/Check-the-IP-Address-in-Linux
• following the install instructions from tracks
• sudo gem install bundler
• mkdir ~/Sites
• cd ~/Sites
• git clone https://github.com/TracksApp/tracks.git
• cd tracks
• bundle install --without development test
• cd config
• cp database.yml.tmpl database.yml
• cp site.yml.tmpl site.yml
• edit database.yml to use the sqlite3 lines
• don’t really care about the security so I didn’t amend site.yml
• cd .. to move to the /tracks directory
• precompile the assets
  • bundle exec rake db:migrate RAILS_ENV=production
• open port 3000 in VM
  • sudo ufw allow 3000
  • https://docs.bitnami.com/virtual-machine/faq/#how-to-open-the-server-ports-for-remote-access
• amend production.rb in confg/environment/ to have config.serve_static_files = true
  • https://stackoverflow.com/questions/17904949/rails-app-not-serving-assets-in-production-environment
• I change VM to local network (Host-only) to avoid firewall issues 192.168.245.128
• cd ~/Sites/tracks
• start app with bundle exec rails server -e production -b 0.0.0.0 -p 3000
  • use -b 0.0.0.0 to map to external facing ’localhost’
  • https://community.bitnami.com/t/cannot-load-rails-page/36083

Turnkey Icon Workarounds

Stas Wasserman was kind enough to describe some additional information and workarounds on the Turnkey install:

• The option of using Turnkey is available, with a minor, but quite annoying issue in Tracks UI.
• (I know, the problem is not related to API, but it makes Tracks UI exploration a bit puzzling)
• This issue is with missing icons in Tracks from Turnkey. For example, the start and the edit icons are missing for existing actions in a project (you can see the missing resources error in a browser dev console).
• The issue is mentioned here: turnkeylinux.org/forum/support/20130805/missing-icons-latest-tracks-121-appliance
• The proposed workaround worked for me with a minor tweak (added RAILS_ENV=production , as suggested on the Tracks GitHub page : github.com/TracksApp/tracks/blob/v2.3.0/doc/installation.md:

bundle exec rake assets:precompile RAILS_ENV=production

• You need to run this in Linux command line (or SSH) on the VM.
• Then, after restarting my virtual machine, I have got the icons after login into Tracks.
• Hope this helps, in case other students will face a similar issue.