{"id":13596412,"url":"https://github.com/tkadlec/grunt-perfbudget","last_synced_at":"2025-04-09T16:32:34.889Z","repository":{"id":17058040,"uuid":"19822659","full_name":"tkadlec/grunt-perfbudget","owner":"tkadlec","description":"Grunt task for performance budgeting.","archived":false,"fork":false,"pushed_at":"2024-04-01T18:03:40.000Z","size":58,"stargazers_count":855,"open_issues_count":19,"forks_count":37,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-03-30T23:02:20.626Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkadlec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MIT","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-15T14:35:47.000Z","updated_at":"2025-02-28T03:02:23.000Z","dependencies_parsed_at":"2023-01-13T19:08:02.750Z","dependency_job_id":"e0f1f175-cf74-43fa-af78-c81eedd26b0e","html_url":"https://github.com/tkadlec/grunt-perfbudget","commit_stats":{"total_commits":64,"total_committers":10,"mean_commits":6.4,"dds":0.1875,"last_synced_commit":"9fa751782d19441e55ecb5217fe73343358a2d30"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkadlec%2Fgrunt-perfbudget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkadlec%2Fgrunt-perfbudget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkadlec%2Fgrunt-perfbudget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkadlec%2Fgrunt-perfbudget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkadlec","download_url":"https://codeload.github.com/tkadlec/grunt-perfbudget/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248067920,"owners_count":21042379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:02:25.041Z","updated_at":"2025-04-09T16:32:29.880Z","avatar_url":"https://github.com/tkadlec.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Analyzers","Build Tools to set up performance budget"],"sub_categories":["Meetups"],"readme":"# grunt-perfbudget\n\n\u003e Grunt task for Performance Budgeting\n\n### Performance budgeting thanks to the magic of WebPageTest\n\ngrunt-perfbudget is a [Grunt.js](https://github.com/cowboy/grunt/) task for enforcing a performance budget ([more on performance budgets](http://timkadlec.com/2013/01/setting-a-performance-budget/)). It uses the wonderful [webpagetest.org](http://webpagetest.org) and the [WebPagetest API Wrapper for NodeJS](https://github.com/marcelduran/webpagetest-api) created by [Marcel Duran](https://github.com/marcelduran).\n\ngrunt-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.\n\n## Getting Started\nThis plugin requires Grunt `~0.4.1`\n\nIf you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:\n\n```shell\nnpm install grunt-perfbudget --save-dev\n```\n\nOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:\n\n```js\ngrunt.loadNpmTasks('grunt-perfbudget');\n```\n\n## The \"perfbudget\" task\n\n### Required configuration properties\n\nWhile 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](http://www.webpagetest.org/forums/showthread.php?tid=466) on the WebPagetest forums.\n\nThese can be set in your Gruntfile.js config file like so:\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE'\n    }\n  }\n}\n```\n\nWith these configuration properties set, you can add `perfbudget` to your default tasks list. That'll look something like this:\n\n    grunt.registerTask('default', ['jshint', 'perfbudget']);\n\nWith this in place, grunt-perfbudget will now test your site against the default performance budget settings to see if you're passing.\n\n\n### Options\n\ngrunt-perfbudget takes the following options:\n\n#### options.output\n\nType `String`\nDefault value: NONE\n\nThe file to output the JSON results to.\n\n#### options.url\n\nType `String`\nDefault value: NONE\n\nThe url you want to perform the tests on.\n\n#### options.key\n\nType `String`\nDefault value: NONE\n\nThe API Key for the public instance of WPT. *Not needed if using a private instance of webpagetest*\n\n#### options.location\n\nType `String`\nDefault value: 'Dulles_Nexus5'\n\nThe default WPT location/device to conduct the test using.\n\n#### options.wptInstance\n\nType `String`\nDefault value: 'www.webpagetest.org'\n\nThe WPT instance to conduct the tests with.\n\n#### options.pollResults\n\nType `Number`\nDefault value: 5\n\nThe frequency (in seconds) to poll for results after the test has been scheduled.\n\n#### options.timeout\n\nType `Number`\nDefault value: 60\n\nTimeout (in seconds) for the tests to run.\n\n#### options.connectivity\n\nType `String`\nDefault value: NONE\n\nThe connectivity profile to use. WPT provides the following options: Cable, DSL, FIOS, Dial, 3G, Native, custom.\n\n#### options.bandwidthDown\n\nType `String`\nDefault value: NONE\n\nThe download bandwith in Kbps. *Used when connectivity is set to `custom`.*\n\n#### options.bandwidthUp\n\nType `String`\nDefault value: NONE\n\nThe upload bandwith in Kbps. *Used when connectivity is set to `custom`.*\n\n#### options.latency\n\nType `String`\nDefault value: NONE\n\nThe RTT latency in milliseconds. *Used when connectivity is set to `custom`.*\n\n#### options.packetLossRate\n\nType `String`\nDefault value: NONE\n\nThe package loss rate (percentage of packets to drop). *Used when connectivity is set to `custom`.*\n\n#### options.repeatView\n\nType `Boolean`\nDefault value: `false`\n\nIf 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.*\n\n#### options.login\n\nType `String`\nDefault value: NONE\n\nUsername for authenticating tests.\n\n#### options.password\n\nType `String`\nDefault value: NONE\n\nPassword for authenticating tests.\n\n#### options.authenticationType\n\nType `Number`\nDefault value: 0\n\nType of authentication. 0 = Basic, 1 = SNS.\n\n#### options.runs\n\nType `Number`\nDefault value: 1\n\nNumber of test runs. *If the test is run more more than once, the budget is tested against the median result of the runs.*\n\n#### options.budget\n\nType `Object`\n\nAllows 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.*\n\nThe variables you can use as a budget include:\n\n##### budget.visualComplete\n\nType `String`\nDefault value: NONE\n\nThe budget for visually complete in millseconds.\n\n##### budget.render\n\nType `String`\nDefault value: 1000\n\nThe budget for start render time in millseconds.\n\n##### budget.loadTime\n\nType `String`\nDefault value: NONE\n\nThe budget for load time in millseconds.\n\n##### budget.docTime\n\nType `String`\nDefault value: NONE\n\nThe budget for `document.complete` in millseconds.\n\n##### budget.fullyLoaded\n\nType `String`\nDefault value: NONE\n\nThe budget for fully loaded time in millseconds.\n\n##### budget.bytesIn\n\nType `String`\nDefault value: NONE\n\nThe budget for overall weight in bytes.\n\n##### budget.bytesInDoc\n\nType `String`\nDefault value: NONE\n\nThe budget for number of bytes downloaded before the Document Complete time.\n\n##### budget.requests\n\nType `String`\nDefault value: NONE\n\nThe budget for overall number of requests.\n\n##### budget.requestsDoc\n\nType `String`\nDefault value: NONE\n\nThe budget for number of requests made before the Document Complete time.\n\n##### budget.SpeedIndex\n\nType `String`\nDefault value: 1000\n\nThe budget for calculated SpeedIndex.\n\n##### budget.userTime\n\nType `String`\nDefault value: NONE\n\nThe budget for the final user timing mark recorded on the page.\n\nYou can test against a specific user timing mark like so:\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE',\n      budget: {\n\t\t'userTime.CUSTOM_MARK': '1500'\n      }\n    }\n  }\n}\n```\n\nFor more information on User Timing, see [http://www.w3.org/TR/user-timing/](http://www.w3.org/TR/user-timing/)\n### Usage Examples\n\n#### 1. Test http://google.com against default budget settings\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE'\n    }\n  }\n}\n```\n\n#### 2. Test http://google.com using custom budget for SpeedIndex and Visually Complete\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE',\n      budget: {\n\t\tvisualComplete: '4000',\n\t\tSpeedIndex: '1500'\n      }\n    }\n  }\n}\n```\n\n#### 3. Test URL using custom budget and private WPT Instance\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      wptInstance: 'http://PRIVATE_INSTANCE.com',\n      budget: {\n\t\tvisualComplete: '4000',\n\t\tSpeedIndex: '1500'\n      }\n    }\n  }\n}\n```\n\n#### 4. Test http://google.com using a custom budget against the median result of 5 test runs.\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE',\n      runs: 5,\n      budget: {\n\t\tvisualComplete: '4000',\n\t\tSpeedIndex: '1500'\n      }\n    }\n  }\n}\n```\n\n#### 5. Test http://google.com against default budget settings and output the results to a file.\n\n```javascript\nperfbudget: {\n  default: {\n    options: {\n      url: 'http://google.com',\n      key: 'API_KEY_HERE',\n      output: 'wpt-results.json'\n    }\n  }\n}\n```\n\n## Contributing\nIn 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](http://gruntjs.com/).\n\n## Release History\n- Version 0.1.3: Bug fix for custom options. Now includes ability to use HTTP authentication on tests.\n- Version 0.1.4: Ability to define custom number of test runs.\n- Version 0.1.5: Improved polling using the underlying API. Users can now set polling frequency as well as a timeout for tests.\n- Version 0.1.6: Ability to test budget against repeat views; minor bug fixes; better error handling.\n- Version 0.1.7: Improved error handling.\n- Version 0.1.8: Ability to output results to JSON; bug fixes; improved error handling.\n- Version 0.1.9: Security improvements. Also changing default instance of WPT to use https now that the site supports it.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkadlec%2Fgrunt-perfbudget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkadlec%2Fgrunt-perfbudget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkadlec%2Fgrunt-perfbudget/lists"}