From f3a6ceb46c4a7642b9a674b2a456b76facf577bb Mon Sep 17 00:00:00 2001 From: Amit Davidi Date: Wed, 22 Jul 2020 17:45:44 +0300 Subject: [PATCH] Improve feature documentation --- docs/APIRef.ActionsOnElement.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/APIRef.ActionsOnElement.md b/docs/APIRef.ActionsOnElement.md index eabd05686f..3d008a58ef 100644 --- a/docs/APIRef.ActionsOnElement.md +++ b/docs/APIRef.ActionsOnElement.md @@ -244,21 +244,32 @@ jestExpect(multipleMatchedElements.elements[0].identifier).toBe('FirstElement'); ### `takeScreenshot()` Android Only -Take a screenshot of the native view associated with the element in question. Useful for highly-focused visual comparison tests (i.e. comparison between elements rather than a whole screen). +Take a screenshot of the native view associated with the element in question. Useful for highly-focused visual comparison tests (i.e. comparison between elements rather than of complete screen, with visual "noise"). Returns the path of a temporary file containing the resulted `.png` image. ```js const bitmapPath = await element(by.id('fancy-element')).takeScreenshot(); +``` + +A typical use case of this API is like so (i.e. taking a screenshot and saving the resulted image once, then keeping it as a snapshot of the expected result): +```js const fs = require('fs'); -const bitmapBuffer = fs.readFileSync(bitmapPath); +const bitmapBuffer = fs.readFileSync(bitmapPath); // bitmapPath: see above const snapshottedBitmapBuffer = fs.readFileSync(snapshottedBitmapPath); if (!bitmapBuffer.equals(expectedBitmapBuffer)) { throw new Error('Bitmaps differ!'); } ``` +> A more useful way of doing this is by utilizing more advanced 3rd-party image snapshotting and comparison tools such as [applitools](https://applitools.com). + +Caveats: + +* Currently, the image-file generated by Detox is stored in a temporary folder, and does not get automatically cleaned-up. +* The image-file does not get exported as a test artifact in the test's finalization (i.e. such as with [device.takeScreenshot(name)](https://github.com/wix/Detox/blob/master/docs/APIRef.DeviceObjectAPI.md#devicetakescreenshotname)). + ## Deprecated Methods - [`.tapAtPoint()`](#tapatpointpoint)