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.
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.
At WonderProxy, proxy tokens replace passwords in your server credentials. Proxy tokens are quick to generate and work instantly across the network. Generate one (or five), and then use them anywhere your proxy configuration asks for a password.
Proxy tokens are part of our Delegated Authentication system.
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="wonderProxyUsername" export WONDERPROXY_PASS="wonderProxyProxyToken"
This also makes it easier to use Sauce Labs' Sauce Connect tool directly if you choose not to use our scripts.
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.
ping, or through our API.
Step 1: Set up Sauce Connect.
- To get started, download the Sauce Connect executable from Sauce Labs.
Open a Sauce Connect tunnel. You can either do this
scor use the WonderProxy helper scripts.
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
Use WonderProxy helper scripts:
To use our helper scripts, the
scbinary must be in your environment
$PATHvariable. On most Linux and Mac systems, you can do that by copying
sauce_connect.shcreates 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.
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
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
id attribute of
Since Sauce Labs' Sausage library extends the PHPUnit testing framework
we can use PHPUnit's
functionality to inject the expected
for each location. In this case, the
source is an abstract method:
With our tests defined in
can use child classes to override the data provider and inject
location-specific content. Above, we used
to identify the Sauce Connect tunnel we should use.
The only remaining piece is the location-specific
Step 4: Run the Tests!
We've written our tests, so let's kick them off! The Sausage
library provides the
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
Alternatively, if you used
sauce_connect.sh to open the
tunnels, you can use
to close them. Specify each tunnel to close in the argument list. The
following example closes the Tel Aviv, Vancouver, and Albuquerque Sauce
./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