Grunt task for Performance Budgeting

grunt-perfbudget is a Grunt.js task for enforcing a performance budget (more on performance budgets). It uses the wonderful webpagetest.org and the WebPagetest API Wrapper for NodeJS created by Marcel Duran.

grunt-perfbudget uses either a public or private instance of WebPagetest to perform tests on a specified URL. It compares test results to budgets you specify. If the budget is met, the tasks successfully completes. If it the page exceeds your performance budgets, the task fails and informs you why.

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-perfbudget --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-perfbudget');

While grunt-perfbudget provides defaults for most configurable options, it does require the URL to be tested, as well as an API key to use if testing against the public instance of WebPagetest. For more information on obtaining a key, see this thread on the WebPagetest forums.

These can be set in your Gruntfile.js config file like so:

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE'
    }
  }
}

With these configuration properties set, you can add perfbudget to your default tasks list. That'll look something like this:

grunt.registerTask('default', ['jshint', 'perfbudget']);

With this in place, grunt-perfbudget will now test your site against the default performance budget settings to see if you're passing.

grunt-perfbudget takes the following options:

Type String Default value: NONE

The file to output the JSON results to.

Type String Default value: NONE

The url you want to perform the tests on.

Type String Default value: NONE

The API Key for the public instance of WPT. Not needed if using a private instance of webpagetest

Type String Default value: 'Dulles_Nexus5'

The default WPT location/device to conduct the test using.

Type String Default value: 'www.webpagetest.org'

The WPT instance to conduct the tests with.

Type Number Default value: 5

The frequency (in seconds) to poll for results after the test has been scheduled.

Type Number Default value: 60

Timeout (in seconds) for the tests to run.

Type String Default value: NONE

The connectivity profile to use. WPT provides the following options: Cable, DSL, FIOS, Dial, 3G, Native, custom.

Type String Default value: NONE

The download bandwith in Kbps. Used when connectivity is set to custom.

Type String Default value: NONE

The upload bandwith in Kbps. Used when connectivity is set to custom.

Type String Default value: NONE

The RTT latency in milliseconds. Used when connectivity is set to custom.

Type String Default value: NONE

The package loss rate (percentage of packets to drop). Used when connectivity is set to custom.

Type Boolean Default value: false

If set to true, tests the budget against the repeat view. By default, perfbudget tests the budget against the first view and doesn't ask WPT to run a test on the repeat view.

Type String Default value: NONE

Username for authenticating tests.

Type String Default value: NONE

Password for authenticating tests.

Type Number Default value: 0

Type of authentication. 0 = Basic, 1 = SNS.

Type Number Default value: 1

Number of test runs. If the test is run more more than once, the budget is tested against the median result of the runs.

Type Object

Allows you to specify a performance budget. If the test is run more more than once, the budget is tested against the median result of the runs.

The variables you can use as a budget include:

Type String Default value: NONE

The budget for visually complete in millseconds.

Type String Default value: 1000

The budget for start render time in millseconds.

Type String Default value: NONE

The budget for load time in millseconds.

Type String Default value: NONE

The budget for document.complete in millseconds.

Type String Default value: NONE

The budget for fully loaded time in millseconds.

Type String Default value: NONE

The budget for overall weight in bytes.

Type String Default value: NONE

The budget for number of bytes downloaded before the Document Complete time.

Type String Default value: NONE

The budget for overall number of requests.

Type String Default value: NONE

The budget for number of requests made before the Document Complete time.

Type String Default value: 1000

The budget for calculated SpeedIndex.

Type String Default value: NONE

The budget for the final user timing mark recorded on the page.

You can test against a specific user timing mark like so:

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE',
      budget: {
		'userTime.CUSTOM_MARK': '1500'
      }
    }
  }
}

For more information on User Timing, see http://www.w3.org/TR/user-timing/

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE'
    }
  }
}

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE',
      budget: {
		visualComplete: '4000',
		SpeedIndex: '1500'
      }
    }
  }
}

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      wptInstance: 'http://PRIVATE_INSTANCE.com',
      budget: {
		visualComplete: '4000',
		SpeedIndex: '1500'
      }
    }
  }
}

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE',
      runs: 5,
      budget: {
		visualComplete: '4000',
		SpeedIndex: '1500'
      }
    }
  }
}

perfbudget: {
  default: {
    options: {
      url: 'http://google.com',
      key: 'API_KEY_HERE',
      output: 'wpt-results.json'
    }
  }
}

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

• Version 0.1.3: Bug fix for custom options. Now includes ability to use HTTP authentication on tests.
• Version 0.1.4: Ability to define custom number of test runs.
• Version 0.1.5: Improved polling using the underlying API. Users can now set polling frequency as well as a timeout for tests.
• Version 0.1.6: Ability to test budget against repeat views; minor bug fixes; better error handling.
• Version 0.1.7: Improved error handling.
• Version 0.1.8: Ability to output results to JSON; bug fixes; improved error handling.
• Version 0.1.9: Security improvements. Also changing default instance of WPT to use https now that the site supports it.