{"id":19151425,"url":"https://github.com/sc5/sc5-styleguide-visualtest","last_synced_at":"2025-06-12T03:08:23.733Z","repository":{"id":65374154,"uuid":"42988498","full_name":"SC5/sc5-styleguide-visualtest","owner":"SC5","description":"Gulp plugin for automatic visual testing SC5 StyleGuide components","archived":false,"fork":false,"pushed_at":"2018-03-23T08:51:57.000Z","size":359,"stargazers_count":24,"open_issues_count":12,"forks_count":8,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-18T02:22:58.067Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/SC5.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-23T08:33:05.000Z","updated_at":"2021-06-17T00:26:18.000Z","dependencies_parsed_at":"2023-01-20T00:55:16.178Z","dependency_job_id":null,"html_url":"https://github.com/SC5/sc5-styleguide-visualtest","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide-visualtest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide-visualtest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide-visualtest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SC5%2Fsc5-styleguide-visualtest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SC5","download_url":"https://codeload.github.com/SC5/sc5-styleguide-visualtest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252819555,"owners_count":21809038,"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-11-09T08:14:40.739Z","updated_at":"2025-05-07T05:24:30.905Z","avatar_url":"https://github.com/SC5.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sc5-styleguide-visualtest\n\nA gulp plugin for automatic visual testing between different versions of components in SC5 StyleGuide.\n\nThe screenshots are taken in Chrome via PhantomJS.\n\n## Technical requirements\n\nYou need to have PhantomJS installed. After that:\n\n```\nnpm install --save-dev sc5-styleguide-visualtest\n```\n\n## Taking the grid screenshots\nFirst you will need to create a set of grid images. They are usually taken from production version of the Style Guide.\nIt is nice to have a Gulp task for it because you will need to remake the grid screenshots after every interface change.\n\n```js\nvar gulp = require(\"gulp\");\n\nvar visTest = require('sc5-styleguide-visualtest');\nvar minimist = require('minimist');\n\nvar knownOptions = {\n  'string': 'section',\n  'default': { 'section': false }\n};\n\nvar options = minimist(process.argv.slice(2), knownOptions);\n\ngulp.task(\"test:visual:update\", function() {\n  gulp.src('path/to/styleguide/outpurDir', { read: false })\n    .pipe(visTest.gather({\n      configDir: './tests/visual/config', // Path to configuration and tests\n      excludePages: [\n        '2.2.1', // Back icon is not shown in prod\n        '6.1-2', // picture is not loaded in prod\n      ],\n      gridScreenshotsDir: './tests/visual/grid-screenshots',\n      rootUrl: 'http://mycompany.com/styleguide',\n      sections: options.section\n    }))\n    .pipe(gulp.dest('./tests/visual/config'));\n});\n```\n\nYou may also use `localhost` version of Style Guide in `rootUrl` when taking screenshots. If so, make sure it runs.\n\nThese 2 tasks will create a basic configuration in `tests/visual/config` folder (you can change to any other path). In\nthis folder you will get:\n* list of fullscreen pages of your components and their modifiers, excluding the listed\n* basic test\n* grid screenshots put into `tests/visual/grid-screenshots` (change to your path)\n\nStore the configuration files and the screenshots in teh repository. But don't forget to exclude from npm and bower\npackage if you provide it.\n\n## Running tests\nTests will compare the grid screenshots with the current view of your Style Guide.\n\n```js\ngulp.task(\"test:visual\", function(done){\n  gulp.src(styleGuidePath, { read: false })\n    .pipe(visTest.test({\n      configDir: './tests/visual/config',\n      gridScreenshotsDir: './tests/visual/grid-screenshots',\n      rootUrl: 'http://127.0.0.1:8000/#',\n      sections: options.section\n    }));\n});\n```\n\nDon't forget to have the server with StyleGuide running.\n\nAfter running `gulp test:visual` you will get output like this:\n\n```\n✓ 5.1-25 plain [chrome]\n✓ 5.1-26 plain [chrome]\n✓ 5.1-27 plain [chrome]\n✓ 5.1-28 plain [chrome]\n✘ 6.2-1 plain [chrome]\n✘ 6.2-2 plain [chrome]\n✘ 6.2-3 plain [chrome]\n✘ 6.2-4 plain [chrome]\n✘ 6.2-5 plain [chrome]\n```\nThe numbers are the references of components in your StyleGuide.\n\nYou may see the failed tests visually if open `gemini-report/index.html`.\n\nThis is how different problems look when spotted:\n\n**Wrong padding**\n\n![](images/wrong-padding.png)\n\n**Wrong font size**\n\n![](images/wrong-font-size.png)\n\n**Wrong height**\n![](images/wrong-height.png)\n\n## Providing options\nBy default the plugin takes screenshots in desktop resolution. However you may provide\nyour own options and take screenshots in different configuration.\n\n```js\ngulp.task(\"test:visual\", function(done){\n  gulp.src(styleGuidePath, { read: false })\n    .pipe(visTest.test({\n      configDir: './tests/visual/config',\n      gridScreenshotsDir: './tests/visual/grid-screenshots',\n      rootUrl: 'http://127.0.0.1:8000/#',\n      sections: options.section,\n      geminiOptions: {\n        browsers: {\n          \"chrome-latest\": {\n            desiredCapabilities: {\n              browserName: 'chrome',\n              version: '37.0'\n            }\n          }\n        },\n        windowSize: '300x600'\n      }\n    }));\n});\n```\n\nDon't forget to use the same `geminiOptions` object in for both gulp tasks.\n\nCheck the [full list of settings for Gemini](https://en.bem.info/tools/testing/gemini/config/)\n\n## Development flow\n\n### Update the reference images for particular sections (and their subsections)\n\n```\ngulp  test:visual:update --section 1 --section 4.5\n```\n\n### Run tests for particular sections (and the subsections) only\n\n```\ngulp  test:visual --section 1 --section 3.3\n```\n\n## Custom tests\n\nBy default all the components are testing with the same suit. It waits the component to be rendered and then takes a\npicture.\n\nIf you need some specific interactions or modifications for the test, you need to provide a custom test. In the options\nlist the custom test files with `customTests`:\n\n```js\ngulp.task(\"test:visual:update\", function() {\n  gulp.src('path/to/styleguide/outpurDir', { read: false })\n    .pipe(visTest.gather({\n      configDir: './tests/visual/config',\n      gridScreenshotsDir: './tests/visual/grid-screenshots',\n      rootUrl: 'http://mycompany.com/styleguide',\n      customTests: {\n        '2.1': './custom-test.js'\n      },\n      sections: options.section\n    }));\n});\n```\n\nThe paths of the test files should be relative to `configDir`. Then, put the test files in there. The content should be\nlike that:\n\n```js\n'use strict';\n\nvar gemini = require('gemini');\n\nmodule.exports = function (page) {\n  gemini.suite(page.name, function (suite) {\n    suite.setUrl(page.url).setCaptureElements('body').capture('plain', function (actions, find) {\n\n      actions.waitForElementToShow('shadow-dom', 7000);\n      actions.wait(500);\n      // Put your actions here. For example, click on an element\n      actions.click('.simple-block');\n    });\n\n  });\n};\n```\nYou can modify the test as much as needed (however, keep `module.exports = function (page) {` interface). But usually\nthe only needed this is to provide more actions. You can find the full list of possible action in [documentation for\nGemini](https://en.bem.info/tools/testing/gemini/testing/#available-actions).\n\n### Custom core test\n\nIf you need to provide changes for all the tests, it is easier to change the coreTest:\n\n```js\ngulp.task(\"test:visual:update\", function() {\n  gulp.src('path/to/styleguide/outpurDir', { read: false })\n    .pipe(visTest.gather({\n      configDir: './tests/visual/config',\n      gridScreenshotsDir: './tests/visual/grid-screenshots',\n      rootUrl: 'http://mycompany.com/styleguide',\n      coreTest: './custom-core-test.js',\n      sections: options.section\n    }));\n});\n```\n\n### Ignore some parts of the component\n\nWith providing custom test you can ignore some parts of the components. For example, you can tune the test to ignore the\npicture which changes from time to time and never matches, or a blinking thing or such.\n\n```js\nmodule.exports = function (page) {\n  gemini.suite(page.name, function (suite) {\n    suite.setUrl(page.url).setCaptureElements('body').capture('plain', function (actions, find) {\n      ...\n      suite.ignoreElements('.element-to-ignore', '#another-element-to-ignore');\n    });\n\n  });\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsc5%2Fsc5-styleguide-visualtest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsc5%2Fsc5-styleguide-visualtest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsc5%2Fsc5-styleguide-visualtest/lists"}