{"id":13610485,"url":"https://github.com/azachar/protractor-screenshoter-plugin","last_synced_at":"2025-04-12T22:34:03.344Z","repository":{"id":57297149,"uuid":"69283250","full_name":"azachar/protractor-screenshoter-plugin","owner":"azachar","description":"A brand new jasmine2 protractor plugin  that captures for each browser instance a screenshot, console logs, raw HTML and DB dumps. The snapshot is made optionally for each expect or spec. Plugins comes with a beautiful angular based analytics tool to visually check and fix tests results.","archived":false,"fork":true,"pushed_at":"2020-11-25T07:21:23.000Z","size":2453,"stargazers_count":89,"open_issues_count":22,"forks_count":24,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-24T01:15:37.725Z","etag":null,"topics":["console-visualization","dump","html","logs","protractor-e2e-test","report","screenshot-testing","screenshot-utility","screenshots"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"abhishekswain/jasmine2-protractor-utils","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azachar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2016-09-26T19:04:00.000Z","updated_at":"2023-12-30T21:31:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/azachar/protractor-screenshoter-plugin","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azachar%2Fprotractor-screenshoter-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azachar%2Fprotractor-screenshoter-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azachar%2Fprotractor-screenshoter-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azachar%2Fprotractor-screenshoter-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azachar","download_url":"https://codeload.github.com/azachar/protractor-screenshoter-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248642224,"owners_count":21138349,"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":["console-visualization","dump","html","logs","protractor-e2e-test","report","screenshot-testing","screenshot-utility","screenshots"],"created_at":"2024-08-01T19:01:45.120Z","updated_at":"2025-04-12T22:34:03.069Z","avatar_url":"https://github.com/azachar.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"[![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/protractor-screenshoter-plugin/Lobby)\n[![Open Source Helpers](https://www.codetriage.com/azachar/protractor-screenshoter-plugin/badges/users.svg)](https://www.codetriage.com/azachar/protractor-screenshoter-plugin)\n\n[![npm](https://img.shields.io/npm/dm/protractor-screenshoter-plugin.svg?style=flat-square)](https://www.npmjs.com/package/protractor-screenshoter-plugin) [![npm](https://img.shields.io/npm/dt/protractor-screenshoter-plugin.svg?style=flat-square)](https://www.npmjs.com/package/protractor-screenshoter-plugin)\n\n[![npm](https://img.shields.io/npm/v/protractor-screenshoter-plugin.svg?style=flat-square)](https://www.npmjs.com/package/protractor-screenshoter-plugin) [![npm](https://img.shields.io/npm/l/protractor-screenshoter-plugin.svg?style=flat-square)](https://www.npmjs.com/package/protractor-screenshoter-plugin) [![Semver](http://img.shields.io/SemVer/2.0.0.png)](http://semver.org/spec/v2.0.0.html) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n[![Dependency Status](https://david-dm.org/azachar/protractor-screenshoter-plugin.svg)](https://david-dm.org/azachar/protractor-screenshoter-plugin) [![devDependency Status](https://david-dm.org/azachar/protractor-screenshoter-plugin/dev-status.svg)](https://david-dm.org/azachar/protractor-screenshoter-plugin#info=devDependencies)\n[![Known Vulnerabilities](https://snyk.io/package/npm/protractor-screenshoter-plugin/badge.svg)](https://snyk.io/package/npm/protractor-screenshoter-plugin)\n\n[![Build Status](https://travis-ci.org/azachar/protractor-screenshoter-plugin.svg?branch=master)](https://travis-ci.org/azachar/protractor-screenshoter-plugin)\n[![Coverage Status](https://img.shields.io/codecov/c/github/azachar/protractor-screenshoter-plugin.svg?style=flat-square)](http://codecov.io/github/azachar/protractor-screenshoter-plugin?branch=master) [![Greenkeeper badge](https://badges.greenkeeper.io/azachar/protractor-screenshoter-plugin.svg)](https://greenkeeper.io/)\n\n\n# protractor-screenshoter-plugin\n\n**It captures screenshots, console logs, raw HTMLs and DB dumps in your e2e protractor tests out-of-box.**\n\n**All is then visualized in a beautiful [HTML5 report analyzer](https://github.com/azachar/screenshoter-report-analyzer).**\n\n**We support multi capabilities and multi browsers instances, too.**\n\n## Features\n\n1. This plugin can take screenshots of each **Jasmine2** expect **success/failure** on _multiple-browsers instances_ at once.\n2. It can take **screenshots** of each **spec** failure/success as well\n3. For each **expectation** or spec can capture console logs for **each browser instance**\n4. It can generate a report analyzer - angular+bootstrap **HTML reports** with active filtering to easily find out why your tests are failing\n5. HTML reports allow you to analyze your browser's **console logs** as well.\n6. Supports extracting build information (the report displays a build number, a branch, etc. ) for [GitLab](https://gitlab.com) **CI/CD**, [CircleCI](https://circleci.com) and [Travis](https://travis-ci.org/).\n7. Supports parallel tests execution\n8. Makes optional **Ascii** screenshots\n9. **Multi capabilities** are supported\n10. For each expectation or spec can capture **raw HTML** for each browser instance\n11. For each expectation or spec can obtain a **DB dump** via a function returning ``callback(err, dumpAsString)``\n\n\nAdditional HTML reporter features:\n\n1. domain log filter (to narrow down your test classes faster)\n2. excludes certain repetitive logs\n3. opens for each screenshot its rendered HTML code\n\n## Screenshots\n\n### Reporter Controls\n\n![Screenshoter reporter controlls](https://cdn.rawgit.com/azachar/screenshoter-report-analyzer/master/screenshots/screenshot1.png)\n\n### Expanded Spec\n\n![Screenshoter reporter spec](https://cdn.rawgit.com/azachar/screenshoter-report-analyzer/master/screenshots/screenshot2.png)\n\n### Forked Browser Support\n\n![Screenshoter multi browsers](https://cdn.rawgit.com/azachar/screenshoter-report-analyzer/master/screenshots/screenshot4.png)\n\n### Console log management\n\n![Screenshoter reporter console](https://cdn.rawgit.com/azachar/screenshoter-report-analyzer/master/screenshots/screenshot3.png)\n\n####  Stacktrace filtering\n![Screenshoter reporter stacktrace filtering](https://cdn.rawgit.com/azachar/screenshoter-report-analyzer/master/screenshots/screenshot5.png)\n\n\n## Motivation\n\nThe main motivation to make this fork from \u003chttps://github.com/abhishekswain/jasmine2-protractor-utils\u003e was taking screenshots from multiple browsers at once. So it would allow me to test a chat alike apps where 2+ browsers instances are required to be run from one single test.\n\nLater on, I realized that I want to have a quick overview what is happening with my tests on the CI server. Without even re-running them locally. When something goes wrong you are basically unable to discover it. This plugin allows you to do so.\n\nThe included HTML reporter is Angular based standalone app with a beautiful Bootstrap theme. It allows filtering and narrows down to the root cause. Each screenshot has attached console logs. And we are making screenshots by every expectation not just when the spec is done (this is usually too late to find out, why your test is failing).\n\nUsing this plugin without the HTML report doesn't make sense. The main added value is to have a great analytics tool for your reports that visualize all possible available data to provide a holistic approach.\n\nFrom the code perspective, I split up the report code from the protractor plugin. Perhaps you can plugin in your reporter instead. Also, I think that any open source project must have good test coverage. So I provided the initial set of unit and integrational tests. :beer:\n\nAlso, I created a list of [alternatives](https://github.com/azachar/protractor-screenshoter-plugin/wiki/Alernatives) to this plugin and why I think they are just not good enough.\n\n# How to install\n\nIf your protractor is installed locally, then\n\n```\nnpm install protractor-screenshoter-plugin\n```\n\nIf your protractor is installed globally, then\n```\nnpm install --global protractor-screenshoter-plugin\n```\n\nor install this plugin locally, but then you must specify the plugin's path like this:\n\n```\n    plugins: [{\n        package: 'node_modules/protractor-screenshoter-plugin/index.js',\n        ...\n    }],\n```\nas mentioned in #37.\n\n**NOTE**:\n\n1. This plugin depends on [screenshoter-report-analyzer](https://github.com/azachar/screenshoter-report-analyzer). So sometimes even if this plugin version is not updated, the reporter might be.\n\n2. If you want to use the option `imageToAscii`, then you need to install additional dependencies depending on your OS. By default is this option turned off.\n```sh\n  # Ubuntu\n  sudo apt-get install graphicsmagick\n\n  # Fedora\n  sudo dnf install GraphicsMagick\n\n  # CentOS / RHEL\n  sudo yum install --enablerepo epel GraphicsMagick\n\n  # OS X\n  brew install graphicsmagick\n\n  # Windows users can install the binaries from http://www.graphicsmagick.org/\n  # ...or using the command line:\n  # Chocolatey (package manager for Windows)\n  # (Restart of cmd/PowerShell is required)\n  choco install graphicsmagick\n```\n\n  Then, install this optional package\n```sh\n  npm install image-to-ascii@3.0.11\n```\n\n# Experimental features\n\nPlease always check our branches started with `feat-`. There are some new and shiny features that are working but aren't yet published. Each branch has information how to use it and install it. Once it is stable enough, it will be merged into the master branch.\nFeel free to provide feedback to them.\n\n# Usage\n\nAdd this plugin to the protractor config file:\n\nExample:\n\n```javascript\nexports.config = {\n    framework: 'jasmine2',\n\n    plugins: [{\n        package: 'protractor-screenshoter-plugin',\n        screenshotPath: './REPORTS/e2e',\n        screenshotOnExpect: 'failure+success',\n        screenshotOnSpec: 'none',\n        withLogs: true,\n        writeReportFreq: 'asap',\n        imageToAscii: 'none',\n        clearFoldersBeforeTest: true\n      }],\n\n      onPrepare: function() {\n          // returning the promise makes protractor wait for the reporter config before executing tests\n          return global.browser.getProcessedConfig().then(function(config) {\n              //it is ok to be empty\n          });\n      }\n};\n```\n\nHere is the full list of possible options, more details see below in the [config reference](#config-reference) section.\n\n```javascript\nexports.config = {\n       plugins: [{\n       package: 'protractor-screenshoter-plugin',\n       screenshotOnExpect: {String}    (Default - 'failure+success', 'failure', 'none'),\n       screenshotOnSpec: {String}    (Default - 'failure+success', 'failure', 'none'),\n       htmlOnExpect: {String}    (Default - 'failure', 'failure+success', 'none'),\n       htmlOnSpec: {String}    (Default - 'failure', 'failure+success', 'none'),\n       withLogs: {Boolean}      (Default - true),\n       htmlReport: {Boolean}      (Default - true),\n       screenshotPath: {String}                (Default - '\u003creports/e2e\u003e/screenshots')\n       writeReportFreq: {String}      (Default - 'end', 'spec', 'asap'),\n       verbose: {String} (Default - 'info', 'debug'),\n       pauseOn: {String}    (Default - 'never', 'failure', 'spec'),\n       imageToAscii: {String}    (Default - 'none', 'failure+success', 'failure'),\n       imageToAsciiOpts:{Obbject} (Default - {bg:true})\n       clearFoldersBeforeTest: {Boolean}       (Default - false),\n       failTestOnErrorLog: {\n                failTestOnErrorLogLevel: {Number},  (Default - 900)\n                excludeKeywords: {A JSON Array}\n                suites: {A JSON Array}\n           }\n       }],\n       dumpOnExpect: {String}    (Default - 'failure', 'failure+success', 'none'),\n       dumpOnSpec: {String}    (Default - 'none', 'failure+success', 'failure'),\n       dump: {Function} (Default - null),\n       onPrepare: function () {\n        // returning the promise makes protractor wait for the reporter config before executing tests\n        return global.browser.getProcessedConfig().then(function (config) {\n          //it is ok to be empty\n        });\n       }\n     };\n```\n\n\n## Single browser app\n\nNo need to setup anything special to make screenshots or capture console logs.\n\n## Multi-browser chat alike app\n\nIn order to use multi-browser chat alike testing, you need to keep a track of all browser instances by yourself:\n\nYou can do it like this\n\n```javascript\nvar a  = browser.forkNewDriverInstance();\nvar b  = browser.forkNewDriverInstance();\n\nglobal.screenshotBrowsers['anyCustomNameOfBrowserDisplayedInReports'] = a;\nglobal.screenshotBrowsers.userB = b;\n```\n\nif you close the browser, remove it also from global.screenshotBrowsers After closing browser making screenshots won't work. Make sense, right no browser no screenshot.\n\n```\ndelete global.screenshotBrowsers.userB;\n```\n\nto reset screenshotBrowsers from your previous spec use this code\n\n```javascript\nbeforeAll(function() {\n    global.screenshotBrowsers = {};\n  });\n```\n\n## Running tests in parallel\n\nFor each run of Protractor, it creates separate tests results that are in the end merged into one report.\n\nThe configuration such as this one are supported as of version 0.3.x:\n\n```javascript\nexports.config = {\n    framework: 'jasmine2',\n    //like usual (no change in config api)\n    plugins: [{\n        package: 'protractor-screenshoter-plugin',\n        screenshotPath: './REPORTS/e2e',\n        screenshotOnExpect: 'failure+success',\n        screenshotOnSpec: 'none',\n        withLogs: true,\n        writeReportFreq: 'asap',\n        clearFoldersBeforeTest: true\n    }],\n    //this is new and supported\n    capabilities: {\n        'browserName':'chrome',\n        'shardTestFiles': true,\n        'maxInstances': 5\n    }\n};\n```\n\n\n## Ascii screenshots\nIf there is a failure (based on the config) it creates also an ASCII image into a log file. For this feature, you need to install additional OS dependent libraries. For more information read the [doc imageToAscii](#imagetoascii) bellow.\n\n\n# Config reference\n\n## Environmental variables\n\nScreenshoter out-of-box obtains build information. However, some CI does not have an environmental variable for a commit message. Thus you need to obtain it manually:\n\n**GitLab**\n```sh\n   export CI_COMMIT_MSG=$(git log -1 --pretty=%B)\n```\n\n**CircleCI**\n```sh\n   export CIRCLE_MSG=$(git log -1 --pretty=%B)\n```\n\nIf CI will support one day these variables, you won't need to enter anything in your build process.\n\nDo you want to see exactly what is extracted, consult the code directly [obtainCIVariables](index.js#L551)\n\n## dump\nIf set a function, allows you to run extra command that produce a dump. The dump is taken depending on value in [dumpOnSpec](#dumponspec) or [dumpOnExpect](#dumponexpect).\n\nThis allows you to greater examine your failed expectation/spec from multiple perspectives,\n\none is a screenshot (unfortunately selenium cannot make a whole page screenshot, only what is in the visible browser's window),\n\nthe second is a whole page raw HTML  ( this helps to overcome limitations in seeing only screenshots)\n\nand the third could be for example a DB dump that is all nicely linked to expectations.\n\n_Note_: Implementation of the **dump function** is up to you, you provide any function that **must return a string** directly or in a `callback(err, dumpString)`.\n\nDefault: `null`\n\nValid Options: `null` / `Function`\n\n## dumpOnExpect\n\nCalls the `dump` function for each Jasmine2 expect failure or success, depending on value.\n\nDefault: `'failure'`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## dumpOnSpec\n\nCalls the `dump` function for each Jasmine2 spec failure or success, depending on value.\n\nDefault: `none`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## htmlReport\n\nIf set to `false`, disables HTML report generation.\n\n**NOTE: This tool doesn't really make sense to use without the reports.**\n\nDefault: `true`\n\nValid Options:\n`true`/`false`\n\n## screenshotOnExpect\n\nTakes from each browser instance stored in global.screenshotBrowsers screenshots for each Jasmine2 expect failure or success, depending on value.\n\nDefault: `'failure+success'`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## screenshotOnSpec\n\nTakes from each browser instance stored in global.screenshotBrowsers screenshots for each Jasmine2 spec failure or success, depending on value.\n\nDefault: `failure+success`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## htmlOnExpect\n\nTakes from each browser instance stored in global.screenshotBrowsers raw html for each Jasmine2 expect failure or success, depending on value.\n\nDefault: `'failure'`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## htmlOnSpec\n\nTakes from each browser instance stored in global.screenshotBrowsers raw html for each Jasmine2 spec failure or success, depending on value.\n\nDefault: `'failure'`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\n## pauseOn\n\nIf fails, pause browser on expectation failure or spec failure or never.\n\nDefault: `'never'`\n\nValid Options: `'failure'`/`'spec'`\n\n## verbose\n\nIf set to ``debug`` display internal logging.\n\nDefault: `'info'`\n\nValid Options: `'debug'`/`'info'`\n\n## imageToAscii\n\nAdditionally, make an ASCII image into the console so you can find the issue of you test in your build easier.\n\nPlease note that one of the options of `screenshotOnExpect` or `screenshotOnSpec` must be used to generate the initial screenshot that as additionally transformed into an ASCII image.\n\nIf you are using multiple browsers instances you can disable generating ASCII images individually by setting\n\n```js\nbrowser.skipImageToAscii = true;\n```\nThen this browser instance will be not generated in the log file.\n\nDefault: `'failure'`\n\nValid Options: `'failure+success'`/`'failure'`/`'none'`\n\nTo use this feature please follow instructions on \u003chttps://github.com/IonicaBizau/image-to-ascii/blob/master/INSTALLATION.md\u003e\n\nand also please install the optional dependency\n```\nnpm install image-to-ascii\n```\n\n## imageToAsciiOpts\n\nOptions for imageToAscii conversion, more info can be found at \u003chttps://github.com/IonicaBizau/image-to-ascii\u003e\n\nDefault: ``{bg:true}``\n\n## withLogs (Chrome only)\n\nIf set to `true`, capture from chrome all logs after each expect or spec\n\n_NOTE: This works only on chrome!_\n\nDefault: `true`\n\nValid Options: `true`/`false`\n\nIn order to make chrome' console works properly, you need to modify your `protractor.conf` as follows \u003chttps://github.com/webdriverio/webdriverio/issues/491#issuecomment-95510796\u003e\n\n## writeReportFreq\n\nBy default, the output JSON file with tests results is written at the end of the execution of jasmine tests. However, for debugging, is better to get it written immediately after each expectation - specify the option 'asap'. Also, there is a less usual option to write it after each test - use the option 'spec'. The recommended is to left it out for a CI server and for a local debugging use the option 'asap'.\n\nDefault: `'end'`\n\nValid Options: `'asap'`, `'spec'`, `'end'`\n\n_NOTE: Using option ASAP might introduce unpredictable race conditions if multiple browsers are tested at once. It happens when we automatically collect results of all particulars JSON report files into one final.\n\n## screenshotPath\n\nThe path where the final report including screenshots will be saved. If the path does not exist, will be created. e.g `./reports/something/samewhere/`, please take care of `./` and `/` at the beginning and end.\n\nPlease note that due to an HTML reporter sugar, the final screenshots are stored in the subfolder relative to this $screenshotPath parameter, e.g. in the folder `$screenshotPath/screenshots'`\n\nDefault: `'reports/e2e'`\n\n## clearFoldersBeforeTest\n\nIf this flag set to true, screenshot and HTML report directories will be emptied before generating new reports and screenshots\n\nDefault: `false`\n\n## addPrefixToTests\n\nIf this flag is set to true, a prefix will be added to every test description with the `name` value presented on the `capabilities` object defined on the protractor configs.\n\nDefault: `false`\n\n## failTestOnErrorLog (Chrome only)\n\nContains a set of configuration for console log. When browser console has errors of a certain log level (default:\u003e900), the spec/test is marked failed along with log in the error report/stacktrace.\n\n_NOTE: This works only on chrome!_\n\n### failTestOnErrorLogLevel\n\nLog level, the test fails of the browser console log has logs **more than** this specified level.\n\nDefault: `900`\n\n### excludeKeywords\n\nAn array of keywords to be excluded while searching for error logs. i.e If a log contains any of these keywords, spec/test will not be marked failed.\n\nPlease do not specify this flag, if you don't supply any such keywords.\n\n### suites\n\nAn array of `suites` (protractor.config.suites) where the failTestOnErrorLog will run.\n\nPlease do not specify this flag, if you want all your tests to run through this failTestOnErrorLog validation.\n\n# Development\n\nPlease follow [CONTRIBUTING.md](https://github.com/azachar/protractor-screenshoter-plugin/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazachar%2Fprotractor-screenshoter-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazachar%2Fprotractor-screenshoter-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazachar%2Fprotractor-screenshoter-plugin/lists"}