{"id":24753857,"url":"https://github.com/codeceptjs/codeceptjs-resemblehelper","last_synced_at":"2025-04-07T05:12:58.540Z","repository":{"id":39348293,"uuid":"164664818","full_name":"codeceptjs/codeceptjs-resemblehelper","owner":"codeceptjs","description":null,"archived":false,"fork":false,"pushed_at":"2024-10-23T08:22:09.000Z","size":1281,"stargazers_count":27,"open_issues_count":12,"forks_count":53,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-10-29T11:41:09.996Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/codeceptjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-01-08T14:21:17.000Z","updated_at":"2024-10-23T08:22:11.000Z","dependencies_parsed_at":"2024-04-14T01:49:48.325Z","dependency_job_id":"00c1e09d-8916-4587-aeb1-589dc800e1a8","html_url":"https://github.com/codeceptjs/codeceptjs-resemblehelper","commit_stats":{"total_commits":77,"total_committers":21,"mean_commits":"3.6666666666666665","dds":0.7922077922077921,"last_synced_commit":"0713224f5b8a9f2a6fd924829a4ee0fb98490a22"},"previous_names":["percona-lab/codeceptjs-resemblehelper"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2Fcodeceptjs-resemblehelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2Fcodeceptjs-resemblehelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2Fcodeceptjs-resemblehelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2Fcodeceptjs-resemblehelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeceptjs","download_url":"https://codeload.github.com/codeceptjs/codeceptjs-resemblehelper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595335,"owners_count":20963943,"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":"2025-01-28T11:36:35.653Z","updated_at":"2025-04-07T05:12:58.517Z","avatar_url":"https://github.com/codeceptjs.png","language":"TypeScript","readme":"# codeceptjs-resemblehelper\nHelper for resemble.js, used for image comparison in tests with Playwright, Webdriver, Puppeteer, Appium, TestCafe! \n\ncodeceptjs-resemblehelper is a [CodeceptJS](https://codecept.io/) helper which can be used to compare screenshots and make the tests fail/pass based on the tolerance allowed.\n\nIf two screenshot comparisons have difference greater then the tolerance provided, the test will fail.\n\nNPM package: https://www.npmjs.com/package/codeceptjs-resemblehelper\n\nTo install the package, just run `npm install codeceptjs-resemblehelper`.\n\n### Configuration\n\nThis helper should be added in codecept.json/codecept.conf.js\n\nExample:\n\n```json\n{\n   \"helpers\": {\n     \"ResembleHelper\" : {\n       \"require\": \"codeceptjs-resemblehelper\",\n       \"baseFolder\": \"./tests/screenshots/base/\",\n       \"diffFolder\": \"./tests/screenshots/diff/\",\n       \"prepareBaseImage\": true\n     }\n   }\n}\n```\n\nTo use the Helper, users may provide the parameters:\n\n`baseFolder`: Mandatory. This is the folder for base images, which will be used with screenshot for comparison.\n\n`diffFolder`: Mandatory. This will the folder where resemble would try to store the difference image, which can be viewed later.\n\n`prepareBaseImage`: Optional. When `true` then the system replaces all of the baselines related to the test case(s) you ran. This is equivalent of setting the option `prepareBaseImage: true` in all verifications of the test file.\n\n`compareWithImage`: Optional. A custom filename to compare the screenshot with. The `compareWithImage` file must be located inside the `baseFolder`.\n\n### Usage\n\nThese are the major functions that help in visual testing:\n\nFirst one is the `seeVisualDiff` which basically takes two parameters\n1) `baseImage` Name of the base image, this will be the image used for comparison with the screenshot image. It is mandatory to have the same image file names for base and screenshot image.\n2) `options` options can be passed which include `prepaseBaseImage`, `tolerance` and `needsSameDimension`.\n\n```js\n    /**\n     * Check Visual Difference for Base and Screenshot Image\n     * @param baseImage         Name of the Base Image (Base Image path is taken from Configuration)\n     * @param options           Options ex {prepareBaseImage: true, tolerance: 5, needsSameDimension: false} along with Resemble JS Options, read more here: https://github.com/rsmbl/Resemble.js\n     * @returns {Promise\u003cvoid\u003e}\n     */\n    async seeVisualDiff(baseImage, options) {}\n```\nSecond one is the `seeVisualDiffForElement` which basically compares elements on the screenshot, selector for element must be provided.\n\nIt is exactly same as `seeVisualDiff` function, only an additional `selector` CSS|XPath|ID locators is provided\n```js\n    /**\n     * See Visual Diff for an Element on a Page\n     *\n     * @param selector   Selector which has to be compared, CSS|XPath|ID\n     * @param baseImage  Base Image for comparison\n     * @param options    Options ex {prepareBaseImage: true, tolerance: 5} along with Resemble JS Options, read more here: https://github.com/rsmbl/Resemble.js\n     * @returns {Promise\u003cvoid\u003e}\n     */\n    async seeVisualDiffForElement(selector, baseImage, options){}\n```\n\u003e Note:\n`seeVisualDiffForElement` only works when the page for baseImage is open in the browser, so that WebdriverIO can fetch coordinates of the provided selector.\n\nThird one is the `screenshotElement` which basically takes screenshot of the element. Selector for the element must be provided. It saves the image in the output directory as mentioned in the config folder.\n\n```js\nI.screenshotElement(\"selectorForElement\", \"nameForImage\");\n```\n\u003e Note: This method only works with puppeteer.\n\nFinally to use the helper in your test, you can write something like this:\n\n```js\nFeature('to verify monitoried Remote Db instances');\n\nScenario('Open the System Overview Dashboard', async (I, adminPage, loginPage) =\u003e {\n    adminPage.navigateToDashboard(\"OS\", \"System Overview\");\n    I.saveScreenshot(\"Complete_Dashboard_Image.png\");\n    adminPage.applyTimer(\"1m\");\n    adminPage.viewMetric(\"CPU Usage\");\n    I.saveScreenshot(\"Complete_Metric_Image.png\");\n});\n\nScenario('Compare CPU Usage Images', async (I) =\u003e {\n\n    // setting tolerance and prepareBaseImage in the options array\n    I.seeVisualDiff(\"Complete_Metric_Image.png\", {prepareBaseImage: false, tolerance: 5});\n\n    // passing a selector, to only compare that element on both the images now\n\n    // We need to navigate to that page first, so that webdriver can fetch coordinates for the selector\n    adminPage.navigateToDashboard(\"OS\", \"System Overview\");\n    I.seeVisualDiffForElement(\"//div[@class='panel-container']\", \"Complete_Dashboard_Image.png\", {prepareBaseImage: false, tolerance: 3});\n});\n```\n\u003e Note: `seeVisualDiff` and `seeVisualDiffElement` work only when the dimensions of the screenshot as well as the base image are same so as to avoid unexpected results.\n\n### Ignored Box\nYou can also exclude part of the image from comparison, by specifying the excluded area in pixels from the top left.\nJust declare an object and pass it in options as `ignoredBox`:\n```js\nconst box = {\n    left: 0,\n    top: 10,\n    right: 0,\n    bottom: 10\n};\n\nI.seeVisualDiff(\"image.png\", {prepareBaseImage: true, tolerance: 1, ignoredBox: box});\n```\nAfter this, that specific mentioned part will be ignored while comparison.\nThis works for `seeVisualDiff` and `seeVisualDiffForElement`.\n\n### resemble.js Output Settings\nYou can set further output settings used by resemble.js. Declare an object specifying them and pass it in the options as `outputSettings`:\n\n```js\nconst outputSettings = {\n    ignoreAreasColoredWith: {r: 250, g: 250, b: 250, a: 0},\n    // read more here: https://github.com/rsmbl/Resemble.js\n};\nI.seeVisualDiff(\"image.png\", {prepareBaseImage: true, tolerance: 1, outputSettings: outputSettings});\n```\n\nRefer to the [resemble.js](https://github.com/rsmbl/Resemble.js) documentation for available output settings.\n\n### Skip Failure\nYou can avoid the test fails for a given threshold but yet generates the difference image.\nJust declare an object and pass it in options as `skipFailure`:\n```\nI.seeVisualDiff(\"image.png\", {prepareBaseImage: true, tolerance: 1, skipFailure: true});\n```\nAfter this, the system generates the difference image but does not fail the test.\nThis works for `seeVisualDiff` and `seeVisualDiffForElement`.\n\n\n### Allure Reporter\nAllure reports may also be generated directly from the tool. To do so, add\n\n```\n\"plugins\": {\n\t  \"allure\": {}\n}\n```\n\nin the config file.\nThe attachments will be added to the report only when the calulated mismatch is greater than the given tolerance. \nSet `output` to where the generated report is to be stored. Default is the output directory of the project.\n\n### AWS Support\nAWS S3 support to upload and download various images is also provided.\nIt can be used by adding the *aws* code inside `\"ResembleHelper\"` in the `\"helpers\"` section in config file. The final result should look like:    \n```json\n{\n    \"helpers\": {\n        \"ResembleHelper\" : {\n            \"require\": \"codeceptjs-resemblehelper\",\n            \"baseFolder\": \"\u003clocation of base folder\u003e\",\n            \"diffFolder\": \"\u003clocation of diff folder\u003e\",\n            \"aws\": {\n                \"accessKeyId\" : \"\u003cYour AccessKeyId\u003e\",\n                \"secretAccessKey\": \"\u003cYour secretAccessKey\u003e\",\n                \"region\": \"\u003cRegion of Bucket\u003e\",\n                \"bucketName\": \"\u003cBucket Name\u003e\"\n            }\n        }\n    }\n}\n```\nWhen this option has been provided, the helper will download the base image from the S3 bucket.\nThis base image has to be located inside a folder named \"*base*\".\nThe resultant output image will be uploaded in a folder named \"*output*\" and diff image will be uploaded to a folder named \"*diff*\" in the S3 bucket.\nIf the `prepareBaseImage` option is marked `true`, then the generated base image will be uploaded to a folder named \"*base*\" in the S3 bucket.\n\u003e Note: The tests may take a bit longer to run when the AWS configuration is provided as determined by the internet speed to upload/download images.\n\n### Other S3 Providers\nThe same configuration as above, but with *endpoint* field:\n\n```json\n{\n    \"helpers\": {\n        \"ResembleHelper\" : {\n            \"require\": \"codeceptjs-resemblehelper\",\n            \"baseFolder\": \"\u003clocation of base folder\u003e\",\n            \"diffFolder\": \"\u003clocation of diff folder\u003e\",\n            \"aws\": {\n                \"accessKeyId\" : \"\u003cYour AccessKeyId\u003e\",\n                \"secretAccessKey\": \"\u003cYour secretAccessKey\u003e\",\n                \"region\": \"\u003cRegion of Bucket\u003e\",\n                \"bucketName\": \"\u003cBucket Name\u003e\",\n                \"endpoint\": \"\u003cEndpoint of Bucket\u003e\"\n            }\n        }\n    }\n}\n```\n\n### Compare with custom image\nUsually, every screenshot needs to have the same filename as an existing image inside the `baseFolder` directory. To change this behavior, you can use the `compareWithImage` option and specify a different image inside the `baseFolder` directory.\n\nThis is useful, if you want to compare a single screenshot against multiple base images - for example, when you want to validate that the main menu element is identical on all app pages.\n```js\nI.seeVisualDiffForElement(\"#element\", \"image.png\", {compareWithImage: \"dashboard.png\"});\nI.seeVisualDiffForElement(\"#element\", \"image.png\", {compareWithImage: \"account.png\"});\n```\n\nOr, in some cases there are intended visual differences for different browsers or operating systems:\n```js\nconst os = \"win32\" === process.platform ? \"win\" : \"mac\";\n\n// Compare \"image.png\" either with \"image-win.png\" or \"image-mac.png\":\nI.seeVisualDiff(\"image.png\", {compareWithImage: `image-${os}.png`});\n```\n\n### Known Issues:\n\n\u003e Issue in Windows where the image comparison is not carried out, and therefore no Mismatch Percentage is shown. See 'loadImageData' function in resemble.js\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeceptjs%2Fcodeceptjs-resemblehelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeceptjs%2Fcodeceptjs-resemblehelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeceptjs%2Fcodeceptjs-resemblehelper/lists"}