{"id":17023411,"url":"https://github.com/stefanjudis/grunt-phantomas","last_synced_at":"2025-04-05T23:11:38.173Z","repository":{"id":12328722,"uuid":"14966927","full_name":"stefanjudis/grunt-phantomas","owner":"stefanjudis","description":"Grunt plugin wrapping phantomas to measure frontend performance","archived":false,"fork":false,"pushed_at":"2017-01-09T20:31:30.000Z","size":78012,"stargazers_count":284,"open_issues_count":16,"forks_count":25,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-28T17:56:28.210Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"iTXTech/Genisys","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefanjudis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-05T21:56:20.000Z","updated_at":"2024-11-28T16:28:24.000Z","dependencies_parsed_at":"2022-08-26T03:42:12.808Z","dependency_job_id":null,"html_url":"https://github.com/stefanjudis/grunt-phantomas","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanjudis%2Fgrunt-phantomas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanjudis%2Fgrunt-phantomas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanjudis%2Fgrunt-phantomas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanjudis%2Fgrunt-phantomas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefanjudis","download_url":"https://codeload.github.com/stefanjudis/grunt-phantomas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411239,"owners_count":20934653,"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-10-14T07:13:07.682Z","updated_at":"2025-04-05T23:11:38.156Z","avatar_url":"https://github.com/stefanjudis.png","language":"JavaScript","funding_links":[],"categories":["Metrics Monitor"],"sub_categories":["Meetups"],"readme":"# grunt-phantomas\n\n[![Build Status](http://img.shields.io/travis/stefanjudis/grunt-phantomas.svg?style=flat)](https://travis-ci.org/stefanjudis/grunt-phantomas) [![bnpm version](http://img.shields.io/npm/v/grunt-phantomas.svg?style=flat)](https://www.npmjs.org/package/grunt-phantomas) [![npm downloads](http://img.shields.io/npm/dm/grunt-phantomas.svg?style=flat)](https://www.npmjs.org/package/grunt-phantomas) [![Dependency Status](http://img.shields.io/gemnasium/stefanjudis/grunt-phantomas.svg?style=flat)](https://gemnasium.com/stefanjudis/grunt-phantomas) [![Coverage Status](http://img.shields.io/coveralls/stefanjudis/grunt-phantomas.svg?style=flat)](https://coveralls.io/r/stefanjudis/grunt-phantomas?branch=master) [![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/)\n\n\u003e Grunt plugin for phantomas\n\n[![Maintainers Wanted](https://img.shields.io/badge/maintainers-wanted-red.svg)](https://github.com/pickhardt/maintainers-wanted)\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-phantomas --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-phantomas');\n```\n\n## The \"phantomas\" task\nYou're looking for a tool that gives you detailed metrics about your site? Great!!!\nThis grunt plugin executes [phantomas](https://github.com/macbre/phantomas) for you and visualizes the returned metrics in a generated `index.html` for you. It will keep track of history, so that you can set it up and check reports after every deployment of your site. Read [below](#tracking-history-in-ci) to learn how to setup history tracking in different CI systems.\n\nExamples of rendered output:\n- metrics for [http://gruntjs.com](http://gruntjs.com) -\u003e [here](http://stefanjudis.github.io/grunt-phantomas/gruntjs/)\n- metrics for [example site](http://stefanjudis.github.io/phantomas-custom-metrics-tryout/) including custom metrics -\u003e [here](http://stefanjudis.github.io/phantomas-custom-metrics-tryout/metrics/)\n\n*I'm still at early stage, but I think you can already work with it.* ;)\n\n### Overview\nIn your project's Gruntfile, add a section named `phantomas` to the data object passed into `grunt.initConfig()`.\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    gruntSite : {\n      options : {\n        indexPath : './phantomas/',\n        options   : {},\n        url       : 'http://gruntjs.com/',\n        buildUi   : true\n      }\n    }\n  }\n} )\n```\n\n### Options\n\n#### options.additionalStylesheet\nType: `String|Boolean`\nDefault value: `false`\n\nIf you don't like the phantomas default styling and want to customize it, you can set the path to an additional stylesheet, that will be copied and loaded in the generated `index.html`.\n\n#### options.assertions\nType: `Object`\nDefault Value: `{}`\n\nAn object that represents possible assertions for your generated UI. Best way is to run `grunt-phantomas` once and setting these values afterwards for particular metrics. The UI will warn you whenever the `median` value of your defined runs of a specific metric will go over the specified value by highlighting depending graphs and showing warnings on top of the built UI. Using this option you can easily keep track of getting worse values. Performance budget for the win. :)\n\nExample:\n\n```\nphantomas : {\n  /* https://github.com/stefanjudis/grunt-phantomas */\n  grunt : {\n    options : {\n      assertions : {\n        assetsWithQueryString : 3,     // receive warning, when there are more than 3 assets with a query string\n        bodyHTMLSize          : 10500, // receive warning, when the bodyHTMLsize is bigger than 10500\n        jsErrors              : 0,     // receive warning, when more than 0 JS errors appear\n        gzipRequests          : {      // receive warning, when less compressed assets are loaded then 10 ( might be useful for checking server configurations )\n          type  : '\u003c',\n          value : 10\n        }\n      },\n      indexPath  : './phantomas/',\n      options    : {\n        'timeout' : 30\n      },\n      url        : 'http://gruntjs.com/'\n    }\n  }\n}\n```\n\n#### options.buildUi\nType: `Boolean`\nDefault value: `true`\n\nIf you want to use `grunt-phantomas` without generating a UI for the data, this is an option to switch off the visualization interface. If set to false only defined data format will be outputted at `options.indexPath + '/data/'`.\n\n#### options.indexPath\nType: `String`\nDefault value: `./phantomas/`\n\nA string value that represents the relative path to the place where `phantomas` will render your metrics. Inside of this folder an `index.html`, a data folder and an assets folder will be created.\n\n#### options.limitIncludedRuns\n\nType: `Number|false`\nDefault value: `30`\n\nA numeric value that sets a limit for the included runs inside of the built UI. In case you run `grunt-phantomas` on a hourly/daily basis the generated UI might become slow, because of the big amout of data. Solve this by setting the limit to a lower value.\n\nIn case you are fine with all runs included in the UI set it to `false`.\n\n#### options.numberOfRuns\nType: `Number`\nDefault value: `5`\n\nA numeric value that represents the number of times the `phantomas` executable will be started. The more times it runs the more reliable metrics become.\n\n#### options.options\nType: `Object`\nDefault value: `{}`\n\nAn object that represents possible options for `phantomas` executable. For more information please check [the official api documentation](https://github.com/macbre/phantomas/wiki/npm-module) and [list of possible parameters](https://github.com/macbre/phantomas). See usage examples later on.\n\n#### options.output\nType: `Array`\nDefault value: `[ 'json', 'csv' ]`\n\nChoose to output CSV or JSON files. The default is JSON and CSV. The buildUi option does not work if `json` is not included in `options.output`. *You have to set `buildUi` to `false`, if you want to write CSV files only*.\n\n\n#### options.group\nType: `Object`\nDefault value:\n```\n{\n  'REQUESTS' : [\n    'requests',\n    'gzipRequests',\n    'postRequests',\n    'httpsRequests',\n    'notFound',\n    'multipleRequests',\n    'maxRequestsPerDomain',\n    'domains',\n    'medianRequestsPerDomain',\n    'redirects',\n    'redirectsTime',\n    'smallestResponse',\n    'biggestResponse',\n    'smallestLatency',\n    'biggestLatency',\n    'medianResponse',\n    'medianLatency',\n    'assetsNotGzipped',\n    'assetsWithQueryString',\n    'smallImages'\n  ],\n  'TIMINGS' : [\n    'timeToFirstByte',\n    'timeToLastByte',\n    'timeToFirstCss',\n    'timeToFirstJs',\n    'timeToFirstImage',\n    'fastestResponse',\n    'slowestResponse',\n    'onDOMReadyTime',\n    'onDOMReadyTimeEnd',\n    'windowOnLoadTime',\n    'windowOnLoadTimeEnd',\n    'httpTrafficCompleted',\n    'timeBackend',\n    'timeFrontend'\n  ],\n  'HTML' : [\n    'bodyHTMLSize',\n    'iframesCount',\n    'imagesWithoutDimensions',\n    'commentsSize',\n    'hiddenContentSize',\n    'whiteSpacesSize',\n    'DOMelementsCount',\n    'DOMelementMaxDepth',\n    'nodesWithInlineCSS',\n    'foo'\n  ],\n  'JAVASCRIPT' : [\n    'eventsBound',\n    'documentWriteCalls',\n    'evalCalls',\n    'jsErrors',\n    'consoleMessages',\n    'windowAlerts',\n    'windowConfirms',\n    'windowPrompts',\n    'globalVariables',\n    'localStorageEntries',\n    'ajaxRequests'\n  ],\n  'DOM' : [\n    'DOMqueries',\n    'DOMqueriesById',\n    'DOMqueriesByClassName',\n    'DOMqueriesByTagName',\n    'DOMqueriesByQuerySelectorAll',\n    'DOMinserts',\n    'DOMqueriesDuplicated'\n  ],\n  'HEADERS' : [\n    'headersCount',\n    'headersSentCount',\n    'headersRecvCount',\n    'headersSize',\n    'headersSentSize',\n    'headersRecvSize'\n  ],\n  'CACHING' : [\n    'cacheHits',\n    'cacheMisses',\n    'cachePasses',\n    'cachingNotSpecified',\n    'cachingTooShort',\n    'cachingDisabled'\n  ],\n  'COOKIES' : [\n    'cookiesSent',\n    'cookiesRecv',\n    'domainsWithCookies',\n    'documentCookiesLength',\n    'documentCookiesCount'\n  ],\n  'COUNTS \u0026 SIZES' : [\n    'contentLength',\n    'bodySize',\n    'htmlSize',\n    'htmlCount',\n    'cssSize',\n    'cssCount',\n    'jsSize',\n    'jsCount',\n    'jsonSize',\n    'jsonCount',\n    'imageSize',\n    'imageCount',\n    'webfontSize',\n    'webfontCount',\n    'base64Size',\n    'base64Count',\n    'otherCount',\n    'otherSize'\n  ],\n  'JQUERY' : [\n    'jQueryOnDOMReadyFunctions',\n    'jQuerySizzleCalls'\n  ]\n}\n```\nAn object that represents the metrics grouping rendered inside of the generated `index.html`. You can set up your grouping by just passing another object to this option.\n\nExample:\n\n```\nphantomas : {\n  /* https://github.com/stefanjudis/grunt-phantomas */\n  grunt : {\n    options : {\n      indexPath : './phantomas/',\n      options   : {\n        'timeout' : 30\n      },\n      url       : 'http://gruntjs.com/',\n      group     : {\n        'foo' : [ 'cookiesSent' ]\n      }\n    }\n  }\n}\n```\nThis configuration will lead to a rather empty looking rendered `index.html`. :)\nAdditionally you will be informed, which metrics you missed during the build process.\n\nOutput for example:\n\n```\nCHECKING FOR NOT DISPLAYED METRICS.\n\u003e\u003e You are currently not displaying the following metrics:\n\u003e\u003e requests, gzipRequests, postRequests, httpsRequests, notFound, timeToFirstByte, timeToLastByte, bodySize, contentLength, ajaxRequests, htmlCount, htmlSize, cssCount, cssSize, jsCount, jsSize, jsonCount, jsonSize, imageCount, imageSize, webfontCount, webfontSize, base64Count, base64Size, otherCount, otherSize, cacheHits, cacheMisses, cachePasses, cachingNotSpecified, cachingTooShort, cachingDisabled, consoleMessages, domains, maxRequestsPerDomain, medianRequestsPerDomain, DOMqueries, DOMqueriesById, DOMqueriesByClassName, DOMqueriesByTagName, DOMqueriesByQuerySelectorAll, DOMinserts, DOMqueriesDuplicated, eventsBound, headersCount, headersSentCount, headersRecvCount, headersSize, headersSentSize, headersRecvSize, documentWriteCalls, evalCalls, jQueryOnDOMReadyFunctions, jQuerySizzleCalls, jsErrors, redirects, redirectsTime, assetsNotGzipped, assetsWithQueryString, smallImages, multipleRequests, timeToFirstCss, timeToFirstJs, timeToFirstImage, onDOMReadyTime, onDOMReadyTimeEnd, windowOnLoadTime, windowOnLoadTimeEnd, timeBackend, timeFrontend, httpTrafficCompleted, windowAlerts, windowConfirms, windowPrompts, cookiesRecv, domainsWithCookies, documentCookiesLength, documentCookiesCount, bodyHTMLSize, iframesCount, imagesWithoutDimensions, commentsSize, hiddenContentSize, whiteSpacesSize, DOMelementsCount, DOMelementMaxDepth, nodesWithInlineCSS, globalVariables, localStorageEntries, smallestResponse, biggestResponse, fastestResponse, slowestResponse, smallestLatency, biggestLatency, medianResponse, medianLatency\n```\n\n#### options.url\nType: `String`\nDefault value: `http://gruntjs.com/`\n\nA string value that represents the url of the site, which will be analyzed by `phantomas`.\n\n### Usage Examples\n\n#### Default Options\nIn this example, the default options are used to fetch metrics of `http://gruntjs.com` and render the visualized metrics at `./phantomas`.\n\n```js\ngrunt.initConfig({\n  phantomas: {\n  \tyourSite: {}\n  }\n});\n```\n\n#### Grunt task options\nIn this example, custom options are used to fetch metrics of `http://yoursite.com` and render the visualized metrics at `./yoursite/`.\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yourSite : {\n      options : {\n        additionalStylesheet : '/Users/foo/bar/custom.css',\n        assertions : {\n          'assetsWithQueryString' : 3,\n          'biggestLatency'        : 1400,\n          'bodyHTMLSize'          : 10500,\n          'commentsSize'          : 55,\n          'consoleMessages'       : 0,\n          'hiddenContentSize'     : 65,\n          'jsErrors'              : 0,\n          'gzipRequests'          : 8,\n          'medianResponse'        : 400,\n          'nodesWithInlineCSS'    : 0,\n          'requests'              : 30,\n          'timeToFirstImage'      : 1100,\n          'DOMelementsCount'      : 200,\n          'DOMqueries'            : 10\n        },\n        indexPath            : './yoursite/',\n        url                  : 'http://yoursite.com/',\n        numberOfRuns         : 10\n      }\n    }\n  }\n} );\n```\n\n#### Output options\n\n##### Build ui\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yoursite : {\n      options : {\n        indexPath            : './phantomas/',\n        options              : {\n          'timeout' : 30\n        },\n        url                  : 'http://gruntjs.com/'\n      }\n    }\n  }\n}\n```\n\n##### Export JSON data only\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yoursite : {\n      options : {\n        buildUi              : false,\n        output               : 'json',\n        indexPath            : './phantomas/',\n        options              : {\n          'timeout' : 30\n        },\n        url                  : 'http://gruntjs.com/'\n      }\n    }\n  }\n}\n```\n\n##### Export CSV data only\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yoursite : {\n      options : {\n        buildUi              : false,\n        output               : 'csv',\n        indexPath            : './phantomas/',\n        options              : {\n          'timeout' : 30\n        },\n        url                  : 'http://gruntjs.com/'\n      }\n    }\n  }\n}\n```\n\n#### Phantomas options\nIn this example, the phantomas option is used to set `phantomas` execution parameters. In this case all external script except the defined ones are blocked by `phantomas`, what can become really handy, when dealing with a lot of third party scripts that influence your site performance.\nAdditionally phantomas will wait 30 seconds for all resources to be loaded until it quits with the timeout status code 252.\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yourSite : {\n      options : {\n        indexPath : './yoursite/',\n        options   : {\n          'allow-domain' : 'cdn.yoursite.com.br,ajax.googleapis.com',\n          'no-externals' : true,\n          'timeout'      : 30\n\n        },\n        url       : 'http://yoursite.com'\n      }\n    }\n  }\n} );\n```\n\n### Troubleshooting\n\nBy default, the experimental `film-strip` option is true. If the grunt phantomas command fails, try setting the film strip option to false:\n\n```js\ngrunt.initConfig( {\n  phantomas: {\n    yourSite : {\n      options : {\n        indexPath : './yoursite/',\n        options   : {\n          'film-strip'   : false\n        },\n        url       : 'http://yoursite.com'\n      }\n    }\n  }\n} );\n```\n\n\n### Tracking history in CI\nTo track history in Travis CI, use the [caching option](http://docs.travis-ci.com/user/caching/#Arbitrary-directories) to cache the `indexPath` folder.\n\n#### Note:\nFormatters are not supported as options for Phantomas, because they are not implemented in the CommonJS version of Phantomas.\n\n\n## Donating\nSupport this project and others by [stefanjudis](https://www.gittip.com/stefanjudis/) via [gittip](https://www.gittip.com/stefanjudis/).\n\n[![Support via Gittip](https://rawgithub.com/twolfson/gittip-badge/0.2.0/dist/gittip.png)](https://www.gittip.com/stefanjudis/)\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\nTo make sure tests are passing and coding style is in a good shape please run `grunt test` before applying changes.\n\n## Release History\nPlease check release history at [Github](https://github.com/stefanjudis/grunt-phantomas/releases). :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanjudis%2Fgrunt-phantomas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanjudis%2Fgrunt-phantomas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanjudis%2Fgrunt-phantomas/lists"}