If you’ve got your own Private WebPageTest instance, and you want to add extra locations without setting up the test agents yourself then you can add agents from another instance.

Once configured your local WebPageTest instance submits tests and retrieves results via the API of the remote WebPageTest instance (aka Relay Server), and the pages are tested on the remote instance’s agents.

Using a Relay Server is also handy if you want to do local development on the server code without needing to setup Windows (or mobile) test agents.

Configuration

Assuming you’ve already got a WebPageTest server set up, then adding relay server agents just involves adding some extra entries to locations.ini.

A simple locations.ini that just has the public Singapore test agents as a location looks like this:

[locations]
1=Singapore
default=Singapore

[Singapore]
1=WPT_Singapore
label=Singapore
group=WebPageTest Public

[WPT_Singapore]
browser=Chrome, Firefox, IE 11
label=Singapore
relayServer=https://www.webpagetest.org/
relayKey=(API key for relay server)
relayLocation=ec2-ap-southeast-1

The section for each public agent (WPT_Singapore in this case) has a collection of key / value pairs.

So where do the values for each of these keys come from?

• relayServer

The URL of the WebPageTest instance hosting the agents you want to use.

In this example we’re using the public WebPageTest instance - https://www.webpagetest.org

• relayKey

The API key (if needed) for the WebPageTest instance with the agents.

If you want to use a public agent and don’t already have an API key, thanks to Akamai you can get a key that’s good for 200 tests per day - https://www.webpagetest.org/getkey.php

The Akamai keys only work with a subset of the public locations and a list of those locations is included when the key is emailed to you.

• relayLocation

Each WebPageTest server has a number of agents, you can see these, their browsers and work queues via /getLocations.php

For example on the public instance https://www.webpagetest.org/getLocations.php will show you a list of the locations and browsers at each location.

At the start of each line is a location and browser pair (followed by counts of the number of agents at the location, how many are busy, how many jobs are waiting in each priority queue etc.)

The relayLocation value should be set to the first part of the location:browser pair

For example, the entries for Singapore look something like:

ec2-ap-southeast-1:Chrome   2   0   0   0   0   0   0   0   0   0   0   0   0
ec2-ap-southeast-1:IE 11    2   0   0   0   0   0   0   0   0   0   0   0   0
ec2-ap-southeast-1:Firefox  2   0   0   0   0   0   0   0   0   0   0   0   0
ec2-ap-southeast-1:Safari   2   0   0   0   0   0   0   0   0   0   0   0   0

So to add Singapore, the relayLocation should be set to ec2-ap-southeast-1

• browser

The browser key is a comma separated list of the browsers that are available at your relay location.

So again using the Singapore location from above, the browser key value can be set to Chrome, IE 11, Firefox

(As the Windows version of Safari is so old I never configure it on my instances)

Limitations

There’s a few limitations you want to be aware of when using a relay server:

• If you’re using the public agents then your tests will be run at a lower priority than pages submitted via the public web UI. Your tests are competing with all the other public tests and so are likely to queue.

• If multiple locations use the same relay server then they’ll be duplication in your locations.ini as each location needs to configured separately.

• Requests to the local servers /getLocations.php and getTesters.php won’t show any real detail for the remote test agents.

Further Reading

If you want to know more about WebPageTest Relay Servers there's some docs available - https://sites.google.com/a/webpagetest.org/docs/system-design/webpagetest-relay

And if you want to learn more on how to get the most out of WebPageTest, Rick Viscomi, Marcel Duran and myself wrote 'Using WebPageTest' just for you!