Testing with Sauce Labs and WonderProxy

Overview

When you test your GeoIP websites and applications with WonderProxy, you probably verify things on a few browsers, maybe even on more than one operating system. You're probably not testing exhaustively, though, because who has the time?

Sauce Labs is a paid service that enables you to test applications on virtually infinite (actually >1,000) combinations of browsers, operating systems, and devices. WonderProxy provides a global network of proxy servers that you can use to ensure that your localized applications are behaving properly around the world. With Sauce Labs and WonderProxy, you can run your GeoIP testing through all of the browser-operating system-hardware combinations that you care about, from all of the locales that you care about. Delightful!

In this tutorial, you will learn how to set up Sauce Labs and Sauce Connect to work with WonderProxy to run your automated tests.

For the code samples and setup instructions below, we'll use a working demo, available on Github, that runs sample tests against the WonderNetwork GeoTest page.

Prerequisites

This tutorial requires that you have a Sauce Labs account. To use the Sauce Connect command-line tool, you will also need to retrieve your Sauce Labs Access Key from the Sauce Labs User Settings page.

In order for the WonderProxy demo code to work, export your Sauce Labs and WonderProxy credentials as environment variables, as in the following:

export SAUCE_USERNAME="yourSauceUsername"
export SAUCE_ACCESS_KEY="the-access-key-from-your-account"
export WONDERPROXY_USER="yourWonderProxyUsername"
export WONDERPROXY_PASS="yourWonderProxyPassword"

This also makes it easier to use Sauce Labs' Sauce Connect tool directly if you choose not to use our scripts.

Procedure

Sauce Labs' Sauce Connect is a tool designed to let the Sauce Labs platform access servers that aren't accessible on the public internet by creating a secure tunnel between a local network and Sauce's test platform. As a side benefit, Sauce Connect supports using an authenticated HTTP proxy for its connections — in this case, WonderProxy servers!

You will create a tunnel for each WonderProxy location through which you want to test and point locale-specific tests at the corresponding tunnel. When you run your tests, Sauce Connect will route the tests through the proxies.

Managing multiple Sauce Connect tunnels can be complicated, so WonderProxy provides two helper scripts to open and close Sauce Connect tunnels.

Step 1: Set up Sauce Connect.

1. To get started, download the Sauce Connect executable from Sauce Labs.
2. Open a Sauce Connect tunnel. You can either do this directly using sc or use the WonderProxy helper scripts.
   • Use sc directly: run sc, specifying the relevant proxy details in your command-line arguments, as in the following:

     $ sc --user "$SAUCE_USERNAME" \
          --api-key "$SAUCE_ACCESS_KEY" \
          --proxy "telaviv.wonderproxy.com:11000" \
          --proxy-userpwd "$WONDERPROXY_USER:$WONDERPROXY_PASS"
          --tunnel-identifier telaviv \
          --se-port 4445 \
          --scproxy-port 56692 \
          --pidfile telaviv.pid \
          --logfile telaviv.log

     Refer to the Sauce Connect documentation for more information about each parameter.

     If you plan to run more than one tunnel from the same host computer, be sure to change the --proxy, --tunnel-identifier, --se-port, --scproxy-port, --pidfile, and --logfile arguments.

   • Use WonderProxy helper scripts:
     To use our helper scripts, the sc binary must be in your environment $PATH variable. On most Linux and Mac systems, you can do that by copying sc into your /usr/local/bin directory.

     sauce_connect.sh creates one Sauce Connect tunnel for every WonderProxy server specified in the argument list. The following example creates Sauce Connect tunnels through WonderProxy's Tel Aviv, Vancouver, and Albuquerque proxy servers.

     $ ./sauce_connect.sh telaviv vancouver albuquerque
     
     Starting a Sauce Connect tunnel for telaviv in the background. Check /tmp/sauce-connect/telaviv.* for logs and output.
     When you are ready to stop the telaviv tunnel, kill 88299
     
     Starting a Sauce Connect tunnel for vancouver in the background. Check /tmp/sauce-connect/vancouver.* for logs and output.
     When you are ready to stop the vancouver tunnel, kill 88303
     
     Starting a Sauce Connect tunnel for albuquerque in the background. Check /tmp/sauce-connect/albuquerque.* for logs and output.
     When you are ready to stop the albuquerque tunnel, kill 88307
     
     Tunnels are spinning up, this may take a few seconds...
     ...........................
     telaviv is ready
     vancouver is ready
     albuquerque is ready

The Sauce Labs dashboard displays all of your open tunnels. The Dashboard menu shows the number of active tunnels, and you can select the Tunnels menu item to see details about each tunnel:

Step 2: Link your tests to the Sauce Connect tunnels.

Now that you have Sauce Connect tunnels running through WonderProxy proxies, you can direct your tests through the appropriate tunnels. In the following code samples, we use Sauce Labs' Sausage PHP library, which extends the PHPUnit testing framework for Selenium.

In our sauce_connect.sh script, we set each tunnel's identifier to be the name of the proxy. In our PHPUnit tests, we use a TUNNEL_ID class constant to identify the tunnel that should be used for the test suite:

When you set up your test suite's browser specifications, include the tunnel identifier through which each executed test should run:

For more information about browser specifications, refer to the Sausage documentation.

Step 3: Write your tests.

In order to test through multiple locations, you will need one test suite per tunnel. In the sample code, we use some minor object finagling to let us share our test code across multiple locations.

In the previous step, we created two test classes: AbstractWonderProxyTest and WonderProxyTelAvivTest. The first class,AbstractWonderProxyTest, is where we record any global information such as the URL of the page we're testing:

The abstract class is also where we record the tests themselves. Some tests may be the same regardless of location. The following test checks that the page title is the same regardless of locale:

Other tests will check location-specific content. For example, the following test checks the content of an HTML element with an id attribute of user-city:

Since Sauce Labs' Sausage library extends the PHPUnit testing framework we can use PHPUnit's @dataProvider functionality to inject the expected user-city content for each location. In this case, the @dataProvider source is an abstract method:

With our tests defined in AbstractWonderProxyTest, we can use child classes to override the data provider and inject location-specific content. Above, we used WonderProxyTelAvivTest to identify the Sauce Connect tunnel we should use.

The only remaining piece is the location-specific @dataProvider definition:

Step 4: Run the Tests!

We've written our tests, so let's kick them off! The Sausage library provides the paratest tool, a wrapper for PHPUnit that can run multiple tests in parallel. paratest requires an extra configuration step, so run that first:

$ ./vendor/bin/sauce_config "$SAUCE_USERNAME" "$SAUCE_ACCESS_KEY"

Our sample code has 12 tests (2 tests per location, 2 browsers per location, 3 locations). We'll run eight tests in parallel:

$ ./vendor/bin/paratest --processes 8 --functional tests/

Running phpunit in 8 processes with /path/to/phpunit. Functional mode is ON.

............

Time: 34.5 seconds, Memory: 4.50Mb

OK (12 tests, 12 assertions)

You can track the progress of each test on your Sauce Labs tests page.

Step 5: Troubleshoot

Ideally, your tests will finish without a hitch and you'll be off writing more geo-sensitive code. For the less-than ideal cases, Sauce and PHPUnit still help you out.

If you've been following along with our sample project, you might have noticed some failures: Our geo-location page doesn't place the Tel Aviv server in Holon. When a test on Sauce fails, you'll get the same detailed error report you normally get with your test framework, with the addition of a link to the test in your Sauce Labs account. That's where you can view screenshots, extra details, and even watch a video of the test as it happened.

Step 6: Clean up

When you're done testing, you can close your Sauce Connect tunnels from the Sauce Labs dashboard, or by terminating the sc process with Ctrl-C.

Alternatively, if you used sauce_connect.sh to open the tunnels, you can use sauce_disconnect.sh to close them. Specify each tunnel to close in the argument list. The following example closes the Tel Aviv, Vancouver, and Albuquerque Sauce Connect tunnels.

./sauce_disconnect.sh telaviv vancouver albuquerque
Killing Sauce Connect tunnel for telaviv, PID 88299
Killing Sauce Connect tunnel for vancouver, PID 88303
Killing Sauce Connect tunnel for albuquerque, PID 88307