diff --git a/docs/contributing/index.md b/docs/contributing/index.md index e1165f1371..a33d673a01 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -59,6 +59,9 @@ project. Please read this section carefully if you are interested in contributin * Please squash pull requests down to a single commit to simplify review and keep history clean. * Ensure all new features have unit tests that pass and any bug fixes include tests that fail without the fix applied + [UI Testing](./ui-testing.md) - How to use UI-Test in sandstone source. + [Screenshot Testing](./screenshot-testing.md) - How to use Screenshot-Test in sandstone source. + * Help keep diffs easy to read by not making unnecessary rearrangements to the source code. * Make sure not to inadvertently change line ending types from Unix to Windows. * Ensure inline API documentation exists and is up-to-date (minimum: component summary and descriptions of all diff --git a/docs/contributing/screenshot-testing.md b/docs/contributing/screenshot-testing.md new file mode 100644 index 0000000000..2820e15c02 --- /dev/null +++ b/docs/contributing/screenshot-testing.md @@ -0,0 +1,86 @@ +--- +title: Screenshot Testing +--- + +## What is the Screenshot Testing +Screenshot test is visual test that takes a screenshot, then compares it to a reference screenshot file saved. When ui changes, one of the major considerations is whether visual changes exist. Some changes may be easy to check, but some changes are hard to check due to very small change. With Screenshot test, very small changes can easily check due to compare pixel-by-pixel. Additionally, Screenshot testing is the most reliable test for static images. + +## Prerequisites +Clone sandstone from GitHub, install dependencies and connect the modules using Lerna: + +```shell +# clone the repo! +git clone git@github.com:enactjs/sandstone.git +# move in +cd sandstone +# we're using git flow so develop is our working branch +git checkout develop +# install lerna +npm install +# link dependencies +enact link +``` + +## Creating tests +Within the UI Library, create an app for testing in `./tests/screenshot/apps` and create a corresponding test in `./tests/screenshot/specs`. + + + src + + test + + screenshot + + apps + + component + + testComponent + testComponent.js <-- create app here + + specs + testComponent-specs.js <-- create spec file here + +In screenshot test, create apps to test component. Please refer sample code. +* Button.js + +```JS +import Button from '../../../../Button'; + +const ButtonTests = [ + + +; + +export default ThemeDecorator(app); +``` + +* Button-specs.js + +```JS +const Page = require('@enact/ui-test-utils/utils'); + +describe('Button', function () { + + beforeEach(async function () { + await Page.open(); + }); + + describe('5-way', function () { + it('should focus disabled button on 5-way right', async function () { + await Page.spotlightDown(); + await Page.spotlightSelect(); + }); + }); +}); +``` + +The Page component from `@enact/ui-test-utils/utils/` Page contains useful methods for loading tests. + +## Running Tests +For a single-run, execute `npm run test-ui`. + +* Filtering UI by Component: + + `npm run test-ui -- --spec ` + +* Re-run tests without building: + + `npm run test-ui -- --skip-build` + +* Running with visible browser: + + `npm run test-ui -- --visible` + +* Running with filtering by component and without building: + + `npm run test-ui -- --spec --skip-build` + +## Viewing Test Results +By default, Test result display on console whether pass or fail. +If fail occurs, fail log display in console and you can see the screenshot about fail in `./test/ui/errorShots/`. +Also, you can see the view you made on chrome. This requires that a server be running on port 5000. If you have globally installed the serve command with npm install -g serve you can start the server like this `serve ./test/ui/dist/`. +To open a specific test app, open the URL path for the test. A specific app display as directory in this page. You can see the app as click the app you wanted. + +## Goal of Ui Testing +Manual tests are time consuming and somtimes error occurs. A more efficient approach is to create UI tests so that user tasks are executed in an automated test. With UI test, tests can be executed quickly and reliably in a repeatable way. Simply stated, first priority considering is two things. +* how component handles user actions performed via used input devices. +* whether elements correctly work as intended. \ No newline at end of file