suitest-js-api 3.19.1 → 3.20.0

package/index.d.ts

@@ -50,6 +50,7 @@ import {OcrColor} from './typeDefinition/constants/OcrColor';
 import {ImageChain} from './typeDefinition/ImageChain';
 import {Accuracy} from './typeDefinition/constants/Accuracy';
 import {Lang} from './typeDefinition/constants/Langs';
+import {GetLastVTScreenshotChain} from './typeDefinition/GetLastVTScreenshotChain';
 
 // --------------- Suitest Interface ---------------------- //
 
@@ -66,7 +67,7 @@ declare namespace suitest {
 		releaseDevice(): Promise<void|SuitestError>;
 		startREPL(options?: ReplOptions): Promise<void>;
 		getAppConfig(): Promise<AppConfiguration|SuitestError>;
-		startRecording({webhookUrl}?: {webhookUrl: string}): Promise<void|SuitestError>;
+		startRecording({webhookUrl}?: {webhookUrl: string}): Promise<string|SuitestError>;
 		stopRecording({discard}?: {discard: boolean}): Promise<void|SuitestError>;
 
 		// config
@@ -104,13 +105,13 @@ declare namespace suitest {
 		press(keys: string[], options?: { longPressMs?: string | number }): PressButtonChain;
 		sleep(milliseconds: number): SleepChain;
 		window(): WindowChain;
+		setScreenOrientation(orientation: ScreenOrientationValues): SetScreenOrientationChain;
 		/**
-		 * @description return PromiseLike object with Buffer as value
+		 * @description return PromiseLike object with Buffer as value which represents latest screenshot made for visual testing/assertions
 		 */
 		takeScreenshot(dataFormat?: 'raw'): TakeScreenshotChain<Buffer>;
-		setScreenOrientation(orientation: ScreenOrientationValues): SetScreenOrientationChain;
 		/**
-		 * @description return PromiseLike object with base64 string as value
+		 * @description return PromiseLike object with base64 string as value which represents latest screenshot made for visual testing/assertions
 		 */
 		takeScreenshot(dataFormat: 'base64'): TakeScreenshotChain<string>;
 		/**
@@ -127,6 +128,14 @@ declare namespace suitest {
 		 * suitest.saveScreenshot('{screenshotDir}/{dateTime}-{currentFile}-l{currentLine}.png');
 		 */
 		saveScreenshot(fileName?: string): TakeScreenshotChain<void>;
+		/**
+		 * @description returns a screenshot taken with a previous visual testing assertion (OCR or image assertions). Screenshot data will be provided as a Buffer.
+		 */
+		getLastVTScreenshot(dataFormat?: 'raw'): GetLastVTScreenshotChain<Buffer>;
+		/**
+		 * @description returns a screenshot taken with a previous visual testing assertion (OCR or image assertions). Screenshot data will be provided as a base64 encoded string.
+		 */
+		getLastVTScreenshot(dataFormat: 'base64'): GetLastVTScreenshotChain<string>;
 		openDeepLink(deepLink?: string): OpenDeepLinkChain;
 		ocr(comparators: OcrCommonItem[]): OcrChain;
 		image(imageData: ImageData): ImageChain;

package/lib/api/webSockets.js

@@ -15,7 +15,7 @@ const {handleProgress} = require('../utils/progressHandler');
 const {getInfoErrorMessage} = require('../utils/socketErrorMessages');
 const {translateNotStartedReason} = require('../utils/translateResults');
 const logLevels = require('../../lib/constants/logLevels');
-const {createBufferFromSocketMessage} = require('../utils/socketChainHelper');
+const {createBufferFromSocketMessage, parseBinarySocketMessage} = require('../utils/socketChainHelper');
 
 /**
  * @description print log message that comes from BE side with proper log level
@@ -151,12 +151,22 @@ const webSocketsFactory = (self) => {
 				},
 			});
 
-			// receiving Buffer for previous ws message related to takeScreenshot
 			if (bufferReceived) {
-				const data = screenshotData(message, rawDataMessageId);
+				// if rawDataMessageId specified received buffer should be related to previous takeScreenshot, saveScreenshot ws message
+				if (rawDataMessageId !== null) {
+					const data = screenshotData(message, rawDataMessageId);
 
-				rawDataMessageId = null;
-				handleResponse(data);
+					rawDataMessageId = null;
+					handleResponse(data);
+				}
+				// otherwise should be received binary format which contains json and binary pair for lastScreenshot ws message
+				else {
+					const [text, binaryData] = parseBinarySocketMessage(message);
+					const jsonMessage = JSON.parse(text);
+
+					jsonMessage.content.buffer = binaryData;
+					handleResponse(jsonMessage);
+				}
 			} else if (
 				path([message.messageId, 'contentType'])(requestPromises) === 'takeScreenshot' &&
 				message.content.result === 'success'
@@ -236,7 +246,7 @@ const webSocketsFactory = (self) => {
 
 		/* istanbul ignore else */
 		if (req) {
-			if (['query', 'testLine', 'eval', 'takeScreenshot'].includes(req.contentType)) {
+			if (['query', 'testLine', 'eval', 'takeScreenshot', 'lastScreenshot'].includes(req.contentType)) {
 				req.resolve({
 					...res,
 					contentType: req.contentType,

package/lib/api/wsContentTypes.js

@@ -11,6 +11,7 @@ const contentTypes = {
 	eval: 'eval',
 	testLine: 'testLine',
 	takeScreenshot: 'takeScreenshot',
+	lastScreenshot: 'lastScreenshot',
 	getConfiguration: 'getConfiguration',
 	startRecording: 'startRecording',
 	stopRecording: 'stopRecording',

package/lib/chains/getLastVTScreenshotChain.js

@@ -0,0 +1,56 @@
+const makeChain = require('../utils/makeChain');
+const {
+	makeToStringComposer,
+	makeThenComposer,
+	makeToJSONComposer,
+	abandonComposer,
+} = require('../composers');
+const t = require('../texts');
+const {validate, validators} = require('../validation');
+
+/**
+ * @param {import('../../index.d.ts').ISuitest} classInstance
+ */
+const getLastVTScreenshot = (classInstance) => {
+	const toJSON = () => ({type: 'lastScreenshot'});
+
+	const toStringComposer = makeToStringComposer(toJSON);
+	const thenComposer = makeThenComposer(toJSON);
+	const toJSONComposer = makeToJSONComposer(toJSON);
+
+	const getComposers = (data) => {
+		const output = [
+			toStringComposer,
+			thenComposer,
+			toJSONComposer,
+		];
+
+		if (!data.isAbandoned) {
+			output.push(abandonComposer);
+		}
+
+		return output;
+	};
+
+	/**
+	 * @param {'raw' | 'base64'} [dataFormat]
+	 * @returns {*}
+	 */
+	const getLastVTScreenshotChain = (dataFormat = 'raw') => makeChain(classInstance, getComposers, {
+		type: 'lastScreenshot',
+		dataFormat: validate(
+			validators.LAST_SCREENSHOT,
+			dataFormat,
+			t.invalidInputMessage('getLastVTScreenshot', 'Data format'),
+		),
+	});
+
+	return {
+		getLastVTScreenshot: getLastVTScreenshotChain,
+		// For Unit Testing
+		getComposers,
+		toJSON,
+	};
+};
+
+module.exports = getLastVTScreenshot;

package/lib/commands/startRecording.js

@@ -9,7 +9,7 @@ const {startRecordingMessage} = require('../texts');
 /**
  * Start recording
  * @param {SUITEST_API} instance of main class
- * @returns {ChainablePromise.<void>}
+ * @returns {ChainablePromise.<string>}
  */
 async function startRecording({webSockets, authContext, logger}, recordingSettings) {
 	const webhookUrl = recordingSettings ? recordingSettings.webhookUrl : undefined;

package/lib/composers/thenComposer.js

@@ -29,7 +29,7 @@ const makeThenComposer = (getSocketMessage, callback, beforeSend) => makeMethodC
 				let dataToTranslate = jsonSocketMessage;
 				let snippets;
 
-				if (dataToTranslate.type === 'takeScreenshot') {
+				if (dataToTranslate.type === 'takeScreenshot' || dataToTranslate.type === 'lastScreenshot') {
 					dataToTranslate = {...data};
 					delete dataToTranslate.stack;
 				} else if (data.type === 'runSnippet') {

package/lib/constants/validationKeys.js

@@ -25,6 +25,7 @@ const validationKeys = {
 	STRING: Symbol('string'),
 	HAD_NO_ERROR: Symbol('hadNoError'),
 	TAKE_SCREENSHOT: Symbol('takeScreenshot'),
+	LAST_SCREENSHOT: Symbol('lastScreenshot'),
 	TAP_TYPE: Symbol('tapType'),
 	TAP_TYPE_AND_DURATION: Symbol('tapTypeAndDuration'),
 	DIRECTIONS: Symbol('direction'),

package/lib/utils/AuthContext.js

@@ -39,6 +39,7 @@ const tokenAllowed = {
 		wsContentTypes.eval, wsContentTypes.testLine,
 		wsContentTypes.takeScreenshot, wsContentTypes.getConfiguration,
 		wsContentTypes.startRecording, wsContentTypes.stopRecording,
+		wsContentTypes.lastScreenshot,
 	],
 };
 

package/lib/utils/chainUtils.js

@@ -97,7 +97,7 @@ function getPureComparatorType(def) {
  * @returns {Object}
  */
 function processJsonMessageForToString(jsonMessage) {
-	return !['query', 'takeScreenshot'].includes(jsonMessage.type) && 'request' in jsonMessage
+	return !['query', 'takeScreenshot', 'lastScreenshot'].includes(jsonMessage.type) && 'request' in jsonMessage
 		? jsonMessage.request
 		: jsonMessage;
 }

package/lib/utils/opType.js

@@ -45,6 +45,8 @@ module.exports = {
 				return `|${opTypes.assertLine}|`;
 			case 'takeScreenshot':
 				return `|${opTypes.evalLine}|`;
+			case 'lastScreenshot':
+				return `|${opTypes.evalLine}|`;
 			default:
 				return '';
 		}

package/lib/utils/socketChainHelper.js

@@ -43,6 +43,7 @@ const processServerResponse = (logger, verbosity) =>
 		const isTestLine = res.contentType === 'testLine';
 		const isQuery = res.contentType === 'query';
 		const isTakeScreenshot = res.contentType === 'takeScreenshot';
+		const isLastScreenshot = res.contentType === 'lastScreenshot';
 		const isAborted = res.result === 'aborted';
 
 		// warnings
@@ -146,6 +147,18 @@ const processServerResponse = (logger, verbosity) =>
 			throwErr(new SuitestError(message, SuitestError.EVALUATION_ERROR, responseForError));
 		}
 
+		// getting last screenshot for visual testing
+		if (isLastScreenshot && isSuccess) {
+			if (data.dataFormat === 'raw') {
+				return res.buffer;
+			} else if (data.dataFormat === 'base64') {
+				return res.buffer.toString('base64');
+			}
+		} else if (isLastScreenshot && !isSuccess) {
+			logger.error(infoMessage());
+			throwErr(new SuitestError(message, SuitestError.EVALUATION_ERROR, responseForError));
+		}
+
 		logger.error(infoMessage(''));
 		throwErr(new SuitestError(message, SuitestError.UNKNOWN_ERROR, responseForError));
 	};
@@ -214,6 +227,8 @@ function getResponseForError(res) {
 	return responseForError;
 }
 
+const PROTOCOL_NUMBER = 0x00;
+
 /**
  * @description concat socket message and binary data pair into single binary data
  * protocol is:
@@ -225,7 +240,7 @@ function getResponseForError(res) {
  * @returns {Buffer}
  */
 function createBufferFromSocketMessage([socketMessage, binaryData]) {
-	const protocolNumber = 0x00;
+	const protocolNumber = PROTOCOL_NUMBER;
 	const socketMessageSizeMaxBytes = 4;
 	const socketMessageBuffer = Buffer.from(typeof socketMessage === 'string' ? socketMessage : JSON.stringify(socketMessage));
 	const sizeSocketMessage = Buffer.alloc(socketMessageSizeMaxBytes);
@@ -237,8 +252,36 @@ function createBufferFromSocketMessage([socketMessage, binaryData]) {
 	return Buffer.concat([header, socketMessageBuffer, binaryData]);
 }
 
+/**
+ * @param {Buffer} binarySocketMessage
+ * @returns {null | [string, Buffer]}
+ */
+function parseBinarySocketMessage(binarySocketMessage) {
+	const protocolBufferOffset = 1;
+	const jsonMessageDataSizeOffset = 4;
+	const headerOffset = protocolBufferOffset + jsonMessageDataSizeOffset;
+	const protocolNumber = binarySocketMessage[0];
+
+	if (protocolNumber !== PROTOCOL_NUMBER) {
+		return null;
+	}
+
+	const textSize = binarySocketMessage.readUInt32BE(protocolBufferOffset);
+	const textPart = binarySocketMessage.toString(
+		'utf-8',
+		headerOffset,
+		headerOffset + textSize,
+	);
+	const binaryPart = binarySocketMessage.subarray(headerOffset + textSize);
+
+	return [
+		textPart,
+		binaryPart,
+	];
+}
 module.exports = {
 	processServerResponse,
 	getRequestType,
 	createBufferFromSocketMessage,
+	parseBinarySocketMessage,
 };

package/lib/validation/jsonSchemas.js

@@ -111,6 +111,11 @@ schemas[validationKeys.TAKE_SCREENSHOT] = {
 	'enum': ['raw', 'base64'],
 };
 
+schemas[validationKeys.LAST_SCREENSHOT] = {
+	'type': 'string',
+	'enum': ['raw', 'base64'],
+};
+
 schemas[validationKeys.UUID] = {
 	'type': 'string',
 	'format': 'uuid',

package/lib/validation/validatorsMap.js

@@ -87,6 +87,9 @@ const validatorsMap = {
 	[validationKeys.TAKE_SCREENSHOT]: (value, text) => {
 		return validators.validateJsonSchema(validationKeys.TAKE_SCREENSHOT, value, text);
 	},
+	[validationKeys.LAST_SCREENSHOT]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.LAST_SCREENSHOT, value, text);
+	},
 	[validationKeys.TAP_TYPE_AND_DURATION]: ({tapType, tapDuration}, tapTypeErrorMsg, durationErrorMsg) => {
 		return validators.validateTapTypeAndDuration({tapType, tapDuration}, tapTypeErrorMsg, durationErrorMsg);
 	},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suitest-js-api",
-  "version": "3.19.1",
+  "version": "3.20.0",
   "main": "index.js",
   "repository": "git@github.com:SuitestAutomation/suitest-js-api.git",
   "author": "Suitest <hello@suite.st>",
@@ -94,7 +94,7 @@
   },
   "dependencies": {
     "@suitest/smst-to-text": "^4.13.0",
-    "@suitest/translate": "^4.20.1",
+    "@suitest/translate": "^4.22.0",
     "@types/node": "^14.0.10",
     "ajv": "^6.12.2",
     "ansi-regex": "^5.0.0",

package/suitest.js

@@ -17,6 +17,7 @@ const closeAppFactory = require('./lib/chains/closeAppChain');
 const suspendAppFactory = require('./lib/chains/suspendAppChain');
 const takeScreenshotFactory = require('./lib/chains/takeScreenshotChain');
 const saveScreenshotFactory = require('./lib/chains/saveScreenshotChain');
+const getLastVTScreenshotFactory = require('./lib/chains/getLastVTScreenshotChain');
 const openUrlFactory = require('./lib/chains/openUrlChain');
 const locationFactory = require('./lib/chains/locationChain');
 const applicationFactory = require('./lib/chains/applicationChain');
@@ -139,6 +140,7 @@ class SUITEST_API extends EventEmitter {
 		const {runTestAssert} = runTestFactory(this);
 		const {takeScreenshot} = takeScreenshotFactory(this);
 		const {saveScreenshot} = saveScreenshotFactory(this);
+		const {getLastVTScreenshot} = getLastVTScreenshotFactory(this);
 		const {setScreenOrientation, setScreenOrientationAssert} = setScreenOrientationFactory(this);
 		const {openDeepLink, openDeepLinkAssert} = openDeepLinkFactory(this);
 		const {ocr, ocrAssert} = ocrFactory(this);
@@ -168,6 +170,7 @@ class SUITEST_API extends EventEmitter {
 		this.pollUrl = pollUrl;
 		this.takeScreenshot = takeScreenshot;
 		this.saveScreenshot = saveScreenshot;
+		this.getLastVTScreenshot = getLastVTScreenshot;
 		this.setScreenOrientation = setScreenOrientation;
 		this.openDeepLink = openDeepLink;
 		this.ocr = ocr;

package/typeDefinition/GetLastVTScreenshotChain.d.ts

@@ -0,0 +1,13 @@
+import {
+	Abandable,
+	AbstractChain,
+	Thenable
+} from './modifiers';
+
+export interface GetLastVTScreenshotChain<TResult> extends
+	AbstractChain,
+	Abandable<GetLastVTScreenshotAbandonedChain>,
+	Thenable<TResult>
+{}
+
+interface GetLastVTScreenshotAbandonedChain extends AbstractChain {}