Test local development environments with ngrok

Local development is convenient and fast. It rids us of network latency and allows more rapid iteration while building a website. But the latency is not gone; it’s simply hidden from the group who should be feeling it the most often. Unless you’re regularly throttling your computer during development, it’s likely that you’ve never experienced your work the way the world consumes it.

This article covers a few techniques to help close the gap and detect important performance issues even before deploying to a remote server.

ngrok, a local tunnelling tool

ngrok is a wonderful, general purpose tool. It creates a tunnel from your computer to the web, allowing your local development environment to have a temporary, discardable URL that is just perfect for demos, tests, and other quick, repeatable tasks.

It’s worth saying upfront that the following tests are absolutely not a replacement for real testing, since your production server is undoubtedly configured differently than your local machine. However, preliminary testing is a great way to catch regressions, so using these as a first line of defense is a great way to keep performance in mind while developing.

Read official ngrok site

ngrok + PageSpeed Insights

I first heard of ngrok from Una Kravets’ article detailing how to set up PageSpeed Insights to test performance locally. You can read her article for a detailed walkthrough, but the gist of the story is that PageSpeed Insights is a hosted service, and the test target needs to be publicly available on the web.

We have a PSI test working out of the box in our frontend performance training kit. Here’s the relevant task:

// The variable declarations have been skipped for this snippet.
// Don't expect it to work if you just paste it in your own file.

gulp.task('psi', 'Performance: PageSpeed Insights', function() {
  // Set up a public tunnel so PageSpeed can see the local site.
  return ngrok.connect(4000, function (err_ngrok, url) {
    log(c.cyan('ngrok'), '- serving your site from', c.yellow(url));

    // Run PageSpeed once the tunnel is up.
    psi.output(url, {
      strategy: 'mobile',
      threshold: 80
    }, function (err_psi, data) {
      // Log any potential errors and return a FAILURE.
      if (err_psi) {
        log(err_psi);
        process.exit(1);
      }

      // Kill the ngrok tunnel and return SUCCESS.
      process.exit(0);
    });
  });
});

Note: This snippet was taken from a larger gulpfile. In order to get it working quickly, try downloading our training kit.

ngrok + PSI task in context

ngrok + WebPageTest

Similar to PSI, WebPageTest (WPT) requires a public website to perform its tests. It can be paired with ngrok to test a local environment. In this example, the task simply runs the default WPT test, then opens the results page in your browser:

// ngrok + WebPageTest
// (requires an API key)
gulp.task('wpt', 'Performance: WebPageTest.org', function () {
  var keys = require('./my-secret-file.json');
  var wpt_test = wpt('www.webpagetest.org', keys.wpt);

  // Set up a public tunnel so WebPageTest can see the local site.
  return ngrok.connect(4000, function (err_ngrok, url) {
    log(c.cyan('ngrok'), '- serving your site from', c.yellow(url));

    // The `url` variable was supplied by ngrok.
    wpt_test.runTest(url, function(err_wpt, data_wpt) {
      // Log any potential errors and return a FAILURE.
      if (err_wpt) {
        log(err_wpt);
        process.exit(1);
      }

      // Open window to results.
      var wpt_results = 'http://www.webpagetest.org/result/' + data_wpt.data.testId;
      log(c.green('✔︎  Opening results page:', wpt_results));
      spawn('open', [wpt_results]);
    });
  });
});

See ngrok + WPT task in context

There are other plugins like grunt-perfbudget that use a bit more of the API than my example. Some WPT settings, such as location and connection, can be configured. It also tracks your progress as well, letting you stick to a predefined budget.

ngrok + CSS regression testing

Another clever use is for CSS regression testing. Our friends at Gizra wrote a great walkthrough detailing how they opted for ngrok instead of using the official BrowserStack or SauceLabs tunnels. It can be a nice time-saver if your team uses different systems for development, such as OS X, various flavors of Linux, or others.