If you’re like me and you have ideas to help improve the WebPageTest public instance UI or you want to crush some bugs, you have a couple of development options. If it’s just a tweak to the styles or similar, you could verify the change live in browser developer tools and submit a small pull request to the GitHub repository. New features that are more complex can’t be done as easily on the fly. A development server should be used to ensure the changes work as intended and don’t break anything. So what are the options for testing WebPageTest locally?
Running WebPageTest on your laptop
My first choice is to run the development server on my laptop running OSX. For how easy it is, there are surprisingly few guides written on getting WebPageTest set up for ad hoc development. Here’s an overview of the process:
- Get a clean copy of the code.
- Configure the private instance.
- Configure Apache to point to the server.
The goal is to accomplish these three steps in under five minutes, so I may take some shortcuts or make assumptions about your development environment. I’ll be sure to note these along the way.
1. Clone the latest version from GitHub
If you want simple, this is it. Just download the master at https://github.com/WPO-Foundation/webpagetest/archive/master.zip. Save it anywhere.
Note: If you already have the GitHub Desktop application installed, here’s a shortcut that will clone the repository for you: github-mac://openRepo/https://github.com/WPO-Foundation/webpagetest
It would also be proper version control etiquette to create a new branch for your changes rather than work in the master branch.
2. Point the private instance to the public test agents
This is key. If we’re only interested in making changes to the UI, it’s totally unnecessary to spin up your own test agents. If your change doesn’t depend on live data at all, you could skip this step. For example, the home page is static and as long as you don’t have to submit a test, you can work entirely local. However, most of the site involves configuring and analyzing tests, which definitely requires live data. The trick is that you can let the public instance do the actual testing workload while your private instance simply pulls in the data and displays it.
The WebPageTest API
Now is a good time to bring up the API. Of course, if you already have an API key you can skip this part.
If you want to communicate with the public instance, you’ll need to be authorized. All API users have a unique key, which can be immediately obtained by filling out a short form at http://www.webpagetest.org/getkey.php. After submitting, you’ll be emailed a key. Save this for the next part.
Using the public test agents
If the goal is to simply get test results from an arbitrary test agent, any of the Dulles browsers will do as they’re provisioned for a healthy amount traffic — not that we’ll be producing much. To use one of these test agents, we’ll need to create a file at
www/settings/locations.ini. Note that the source code is bundled with a locations.ini.sample file for reference.
The contents of this file should be:
label=”Dulles, VA – Chrome”
relayKey=[YOUR API KEY HERE]
The relay server and location ensure that we use the public instance and the relay key authorizes the requests. You can skip the overhead of creating a blank file and copy/pasting the configuration above by downloading it as a gist from GitHub and saving it to the
www/settings/ directory. Remember to use your own API key.
3. Configure Apache
OSX already includes Apache, which is needed to run the server, and PHP, which is needed to render the pages. This last step is only a matter of flipping switches and linking the two with WebPageTest.
Open the Apache configuration file at
/etc/apache2/httpd.conf and update the following settings.
#LoadModule php5_module libexec/apache2/libphp5.so
By default, PHP is disabled. Enable it by changing this to:
LoadModule php5_module libexec/apache2/libphp5.so.
Give Apache read/write permissions
Apache needs file permissions to save the test data. Instead of granting the Apache user (
_www) these permissions, just run Apache as yourself. Change this to:
User [YOUR USERNAME HERE]
In case you’re not sure, your username is the output of the
Point to the server code
This sets up the base file path from which requests will be served. By default it is pointing to some local file path (like
/foo). So to point localhost to the WebPageTest web server, change this to:
DocumentRoot "[PATH TO WEBPAGETEST'S WWW DIRECTORY]"
<Directory "[PATH TO WEBPAGETEST'S WWW DIRECTORY]">
Note: If you’ve already got Apache configured for something else, instead you may want to point to WebPageTest’s www directory for only a unique port number.
And that should be it! If you start Apache and navigate to localhost in your browser, you should see the WebPageTest home page. Now you’re ready to start the real work of making the UI changes.
You can find out more about how to use WebPageTest to analyze the performance of websites in my new book, Using WebPageTest.