suitest-js-api 3.12.2 → 3.14.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/SuitestAutomation/suitest-js-api/blob/master/LICENSE)
 [![npm version](https://img.shields.io/npm/v/suitest-js-api.svg?style=flat)](https://www.npmjs.com/package/suitest-js-api)
-[![CircleCI](https://circleci.com/gh/SuitestAutomation/suitest-js-api.svg?style=shield&circle-token=4aced774267b69829bea6d617c873c40010b1a8b)](https://circleci.com/gh/SuitestAutomation/suitest-js-api)
+[![CircleCI](https://circleci.com/gh/SuitestAutomation/suitest-js-api.svg?style=shield)](https://circleci.com/gh/SuitestAutomation/suitest-js-api)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/02661808dc132b86710d/test_coverage)](https://codeclimate.com/github/SuitestAutomation/suitest-js-api/test_coverage)
 [![Maintainability](https://api.codeclimate.com/v1/badges/02661808dc132b86710d/maintainability)](https://codeclimate.com/github/SuitestAutomation/suitest-js-api/maintainability)
 

package/index.d.ts

@@ -47,6 +47,9 @@ import {OcrReadAs} from './typeDefinition/constants/OcrReadAs';
 import {StringPropComparators} from './typeDefinition/constants/PropComparators';
 import {ValueOf} from './typeDefinition/utils';
 import {OcrColor} from './typeDefinition/constants/OcrColor';
+import {ImageChain} from './typeDefinition/ImageChain';
+import {Accuracy} from './typeDefinition/constants/Accuracy';
+import {Lang} from './typeDefinition/constants/Langs';
 
 // --------------- Suitest Interface ---------------------- //
 
@@ -126,6 +129,8 @@ declare namespace suitest {
 		saveScreenshot(fileName?: string): TakeScreenshotChain<void>;
 		openDeepLink(deepLink?: string): OpenDeepLinkChain;
 		ocr(comparators: OcrCommonItem[]): OcrChain;
+		image(imageData: ImageData): ImageChain;
+		image(apiId: string): ImageChain;
 
 		getPairedDevice(): null | {
 			deviceId: string,
@@ -165,6 +170,8 @@ declare namespace suitest {
 		COOKIE_PROP: CookieProp;
 		OCR_READ_AS: OcrReadAs;
 		OCR_COLOR: OcrColor;
+		ACCURACY: Accuracy;
+		LANG: Lang;
 
 		authContext: AuthContext;
 		appContext: Context;
@@ -212,6 +219,8 @@ declare namespace suitest {
 		setScreenOrientation(orientation: ScreenOrientationValues): SetScreenOrientationChain;
 		openDeepLink(deepLink?: string): OpenDeepLinkChain;
 		ocr(comparators: OcrCommonItem[]): OcrChain;
+		image(imageData: ImageData): ImageChain;
+		image(apiId: string): ImageChain;
 	}
 
 	type NetworkLogEvent = {
@@ -354,6 +363,21 @@ declare namespace suitest {
 		color?: ValueOf<OcrColor>,
 		whitelist?: string,
 		blacklist?: string,
-		region?: [x: number, y: number, width: number, height: number],
+		region?: [left: number, top: number, width: number, height: number],
 	}
+
+	type ImageData =
+		| {
+			// image api id from suitest image repository
+			apiId: string,
+		}
+		| {
+			// url to image somewhere in internet
+			url: string,
+		}
+		| {
+			// os path to image somewhere on a disc
+			filepath: string,
+		}
+
 }

package/lib/api/webSockets.js

@@ -15,6 +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');
 
 /**
  * @description print log message that comes from BE side with proper log level
@@ -281,20 +282,26 @@ const webSocketsFactory = (self) => {
 
 	/**
 	 * Send ws message
-	 * @param {Object} content
+	 * @param {Object | [Object, Buffer]} socketMessage
 	 * @returns {Promise}
 	 */
-	function send(content) {
+	function send(socketMessage) {
 		if (ws) {
 			const messageId = uuid();
 
+			const withBinaryData = Array.isArray(socketMessage);
+			const content = withBinaryData ? socketMessage[0] : socketMessage;
 			const msg = JSON.stringify({
 				messageId,
 				content,
 			});
 
 			logger.debug('Sending message:', msg);
-			ws.send(msg);
+			if (withBinaryData) {
+				ws.send(createBufferFromSocketMessage([msg, socketMessage[1]]));
+			} else {
+				ws.send(msg);
+			}
 
 			return handleRequest(messageId, content.type);
 		}

package/lib/chains/imageChain.js

@@ -0,0 +1,168 @@
+const fs = require('fs');
+const {isNil} = require('ramda');
+const {
+	makeToStringComposer,
+	makeThenComposer,
+	makeToJSONComposer,
+	cloneComposer,
+	assertComposer,
+	abandonComposer,
+	timeoutComposer,
+	visibleComposer,
+	notComposer,
+	inRegionComposer,
+	accuracyComposer,
+} = require('../composers');
+const makeChain = require('../utils/makeChain');
+const {getRequestType} = require('../utils/socketChainHelper');
+const {validate, validators} = require('../validation');
+const {invalidInputMessage, imageMalformed} = require('../texts');
+const {applyTimeout, applyNegation} = require('../utils/chainUtils');
+const SuitestError = require('../utils/SuitestError');
+const {fetch} = require('../utils/fetch');
+const {getAccuracy} = require('../composers/accuracyComposer');
+
+/**
+ * @param {import('../../index.d.ts').ISuitest} classInstance
+ */
+const imageChainFactory = (classInstance) => {
+	const toJSON = (data) => {
+		if (isNil(data.comparator)) {
+			throw new SuitestError(imageMalformed(), SuitestError.INVALID_INPUT);
+		}
+
+		const socketMessage = {
+			type: getRequestType(data, false),
+			request: applyTimeout(
+				{
+					type: 'assert',
+					condition: {
+						subject: {
+							type: 'image',
+						},
+						type: applyNegation(data.comparator.type, data),
+					},
+				},
+				data,
+				classInstance.config.defaultTimeout,
+			),
+		};
+
+		const condition = socketMessage.request.condition;
+		const accuracy = getAccuracy(data);
+
+		if (accuracy) {
+			condition.accuracy = accuracy;
+		}
+
+		if (data.imageData.apiId) {
+			condition.subject.apiId = data.imageData.apiId;
+		} else if (data.imageData.url) {
+			condition.subject.url = data.imageData.url;
+		} else if (data.imageData.filepath) {
+			condition.subject.filepath = data.imageData.filepath;
+		}
+
+		if (data.region) {
+			condition.region = data.region;
+		}
+
+		return socketMessage;
+	};
+
+	const toStringComposer = makeToStringComposer(toJSON);
+
+	const thenComposer = makeThenComposer(async(data) => {
+		const socketMessage = toJSON(data);
+
+		if (data.imageData.apiId) {
+			return socketMessage;
+		}
+
+		if (data.imageData.filepath) {
+			const imageBuffer = await fs.promises.readFile(data.imageData.filepath);
+
+			return [socketMessage, imageBuffer];
+		}
+
+		if (data.imageData.url) {
+			const imageBuffer = await (await fetch(data.imageData.url)).buffer();
+
+			return [socketMessage, imageBuffer];
+		}
+
+		return socketMessage;
+	});
+
+	const toJSONComposer = makeToJSONComposer(toJSON);
+
+	const getComposers = (data) => {
+		const output = [
+			toStringComposer,
+			thenComposer,
+			cloneComposer,
+			toJSONComposer,
+		];
+
+		if (!data.isAssert) {
+			output.push(assertComposer);
+		}
+
+		if (!data.isAbandoned) {
+			output.push(abandonComposer);
+		}
+
+		if (!data.isNegated) {
+			output.push(notComposer);
+		}
+
+		if (!data.timeout) {
+			output.push(timeoutComposer);
+		}
+
+		if (!data.region) {
+			output.push(inRegionComposer);
+		}
+
+		if (!data.comparator) {
+			output.push(visibleComposer);
+		}
+
+		if (!data.accuracy) {
+			output.push(accuracyComposer);
+		}
+
+		return output;
+	};
+
+	const makeImageChain = (imageData) => {
+		const unifiedImageData = typeof imageData === 'string'
+			? {apiId: imageData}
+			: imageData;
+
+		return makeChain(
+			classInstance,
+			getComposers,
+			{
+				type: 'image',
+				imageData:
+					validate(
+						validators.IMAGE_DATA,
+						unifiedImageData,
+						invalidInputMessage('image', 'Image data'),
+					),
+			},
+		);
+	};
+
+	return {
+		image: makeImageChain,
+		imageAssert: (data) => makeImageChain(data).toAssert(),
+
+		// for unit tests
+		getComposers,
+		toJSON,
+	};
+};
+
+module.exports = imageChainFactory;

package/lib/chains/ocrChain.js

@@ -6,6 +6,7 @@ const {
 	assertComposer,
 	abandonComposer,
 	timeoutComposer,
+	languageComposer,
 } = require('../composers');
 const makeChain = require('../utils/makeChain');
 const {getRequestType} = require('../utils/socketChainHelper');
@@ -63,6 +64,9 @@ const ocrFactory = (classInstance) => {
 			if (data.ocrItems) {
 				socketMessage.subject.options = data.ocrItems;
 			}
+			if (data.language) {
+				socketMessage.subject.language = data.language;
+			}
 		} else {
 			socketMessage.request = applyTimeout(
 				{
@@ -75,6 +79,9 @@ const ocrFactory = (classInstance) => {
 				data,
 				classInstance.config.defaultTimeout,
 			);
+			if (data.language) {
+				socketMessage.request.condition.language = data.language;
+			}
 			if (data.ocrItems) {
 				socketMessage.request.condition.comparators = validateOcrComparators(data.ocrItems);
 			}
@@ -107,6 +114,10 @@ const ocrFactory = (classInstance) => {
 			output.push(timeoutComposer);
 		}
 
+		if (!data.language) {
+			output.push(languageComposer);
+		}
+
 		return output;
 	};
 

package/lib/composers/accuracyComposer.js

@@ -0,0 +1,24 @@
+const {makeModifierComposer} = require('../utils/makeComposer');
+const composers = require('../constants/composer');
+const {validate, validators} = require('../validation');
+const {invalidInputMessage} = require('../texts');
+
+const accuracyComposer = makeModifierComposer(composers.ACCURACY, ['accuracy'], (_, meta, accuracy) => {
+	return {
+		...meta,
+		accuracy: validate(
+			validators.ACCURACY,
+			accuracy,
+			invalidInputMessage('accuracy', 'Accuracy'),
+		),
+	};
+});
+
+const getAccuracy = (meta) => {
+	return meta.accuracy;
+};
+
+module.exports = {
+	accuracyComposer,
+	getAccuracy,
+};

package/lib/composers/inRegionComposer.js

@@ -0,0 +1,17 @@
+const {makeModifierComposer} = require('../utils/makeComposer');
+const composers = require('../constants/composer');
+const {validate, validators} = require('../validation');
+const {invalidInputMessage} = require('../texts');
+
+const inRegionComposer = makeModifierComposer(composers.IN_REGION, ['inRegion'], (_, meta, region) => {
+	return {
+		...meta,
+		region: validate(
+			validators.REGION,
+			region,
+			invalidInputMessage('region', 'Region'),
+		),
+	};
+});
+
+module.exports = inRegionComposer;

package/lib/composers/index.js

@@ -46,6 +46,9 @@ const attributesComposer = require('./attributesComposer');
 const cssPropsComposer = require('./cssPropsComposer');
 const deepLinkComposer = require('./deepLinkComposer');
 const withPropertiesComposer = require('./withPropertiesComposer');
+const inRegionComposer = require('./inRegionComposer');
+const languageComposer = require('./languageComposer');
+const {accuracyComposer} = require('./accuracyComposer');
 
 module.exports = {
 	abandonComposer,
@@ -98,4 +101,7 @@ module.exports = {
 	cssPropsComposer,
 	deepLinkComposer,
 	withPropertiesComposer,
+	inRegionComposer,
+	languageComposer,
+	accuracyComposer,
 };

package/lib/composers/languageComposer.js

@@ -0,0 +1,18 @@
+const {makeModifierComposer} = require('../utils/makeComposer');
+const composers = require('../constants/composer');
+const {validate, validators} = require('../validation');
+const {invalidInputMessage} = require('../texts');
+
+/**
+ * Defines language method
+ */
+const languageComposer = makeModifierComposer(composers.LANGUAGE, ['language'], (_, meta, value) => ({
+	...meta,
+	language: validate(
+		validators.LANGUAGE,
+		value,
+		invalidInputMessage('language', 'Language'),
+	),
+}));
+
+module.exports = languageComposer;

package/lib/composers/thenComposer.js

@@ -21,8 +21,12 @@ const makeThenComposer = (getSocketMessage, callback, beforeSend) => makeMethodC
 			if (promiseMap.has(data)) {
 				promise = promiseMap.get(data);
 			} else {
-				const socketMessage = getSocketMessage(data);
-				let dataToTranslate = socketMessage;
+				/** @type {Object | [Object, Buffer]} */
+				const message = await getSocketMessage(data);
+				const withBinaryData = Array.isArray(message);
+				const jsonSocketMessage = withBinaryData ? message[0] : message;
+
+				let dataToTranslate = jsonSocketMessage;
 				let snippets;
 
 				if (dataToTranslate.type === 'takeScreenshot') {
@@ -45,16 +49,21 @@ const makeThenComposer = (getSocketMessage, callback, beforeSend) => makeMethodC
 						logger.log(translation);
 					}
 				}
-				promise = authContext.authorizeWs(socketMessage, data.type)
-					.then(() => webSockets.send(socketMessage).then(result => {
-						return callback
-							? callback(result, data, socketMessage)
-							: processServerResponse(logger, config.logLevel)(result, data, socketMessage, snippets);
-					}, error => {
-						return callback
-							? callback(error, data, socketMessage)
-							: processServerResponse(logger, config.logLevel)(error, data, socketMessage, snippets);
-					}))
+
+				promise = authContext.authorizeWs(jsonSocketMessage, data.type)
+					.then(() => {
+						const defaultResponseHandler = processServerResponse(logger, config.logLevel);
+
+						return webSockets.send(message).then(result => {
+							return callback
+								? callback(result, data, jsonSocketMessage)
+								: defaultResponseHandler(result, data, jsonSocketMessage, snippets);
+						}, error => {
+							return callback
+								? callback(error, data, jsonSocketMessage)
+								: defaultResponseHandler(error, data, jsonSocketMessage, snippets);
+						});
+					})
 					.catch(err => {
 						if (err instanceof SuitestError && err.code === SuitestError.AUTH_NOT_ALLOWED) {
 							logger.error(connectionNotEstablished());

package/lib/constants/accuracy.js

@@ -0,0 +1,9 @@
+const ACCURACY = {
+	HIGH: 'high',
+	MEDIUM: 'medium',
+	LOW: 'low',
+};
+
+Object.freeze(ACCURACY);
+
+module.exports = ACCURACY;

package/lib/constants/composer.js

@@ -45,7 +45,10 @@ const composers = {
 	ATTRIBUTES:       Symbol('getAttributes'),
 	CSS_PROPS:        Symbol('getCssProp'),
 	DEEP_LINK:        Symbol('deepLink'),
-	WITH_PROPERTIES:   Symbol('withProperties'),
+	WITH_PROPERTIES:  Symbol('withProperties'),
+	IN_REGION:        Symbol('inRegion'),
+	LANGUAGE:         Symbol('language'),
+	ACCURACY:         Symbol('accuracy'),
 };
 
 Object.freeze(composers);

package/lib/constants/lang.js

@@ -0,0 +1,13 @@
+const LANG = {
+	ENGLISH: 'eng',
+	GERMAN: 'deu',
+	FRENCH: 'fra',
+	ITALIAN: 'ita',
+	DUTCH: 'nld',
+	SPANISH: 'spa',
+	POLISH: 'pol',
+};
+
+Object.freeze(LANG);
+
+module.exports = LANG;

package/lib/constants/validationKeys.js

@@ -35,6 +35,10 @@ const validationKeys = {
 	COOKIE_PROPS: Symbol('cookieProps'),
 	OCR_COMPARATORS: Symbol('ocrComparators'),
 	OCR_OPTIONS: Symbol('ocrOptions'),
+	IMAGE_DATA: Symbol('imageData'),
+	REGION: Symbol('region'),
+	LANGUAGE: Symbol('language'),
+	ACCURACY: Symbol('accuracy'),
 };
 
 Object.freeze(validationKeys);

package/lib/texts.js

@@ -78,6 +78,7 @@ module.exports = {
 	positionIsMalformed: () => 'position command is malformed',
 	relativePositionIsMalformed: () => 'relative position is malformed',
 	assertOcrMalformed: () => 'Assert ocr line is malformed - comparators are missing',
+	imageMalformed: () => 'Image line is malformed',
 
 	unusedLeaves: leaves => `Some of your Suitest chains were not executed.
 Put an "await" in front of those chains or call .abandon() to suppress these warnings.

package/lib/utils/socketChainHelper.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const {Buffer} = require('buffer');
 const {isNil} = require('ramda');
 const assert = require('assert');
 const SuitestError = require('./SuitestError');
@@ -213,7 +214,31 @@ function getResponseForError(res) {
 	return responseForError;
 }
 
+/**
+ * @description concat socket message and binary data pair into single binary data
+ * protocol is:
+ * | protocol number (1 byte) | size of json socket message (32-bit unsigned integer) | socket message | binary data |
+ * example:
+ * | 0x00 | 0x000001c(28) | Buffer.from(JSON.stringify({type: 'eval', request: {}})) | binaryData |
+ * @param {Object|string} socketMessage
+ * @param {Buffer} binaryData
+ * @returns {Buffer}
+ */
+function createBufferFromSocketMessage([socketMessage, binaryData]) {
+	const protocolNumber = 0x00;
+	const socketMessageSizeMaxBytes = 4;
+	const socketMessageBuffer = Buffer.from(typeof socketMessage === 'string' ? socketMessage : JSON.stringify(socketMessage));
+	const sizeSocketMessage = Buffer.alloc(socketMessageSizeMaxBytes);
+
+	sizeSocketMessage.writeUInt32BE(socketMessageBuffer.length);
+
+	const header = Buffer.concat([Buffer.from([protocolNumber]), sizeSocketMessage]);
+
+	return Buffer.concat([header, socketMessageBuffer, binaryData]);
+}
+
 module.exports = {
 	processServerResponse,
 	getRequestType,
+	createBufferFromSocketMessage,
 };

package/lib/utils/testHelpers/index.js

@@ -5,6 +5,9 @@ const {stripAnsiChars} = require('../stringUtils');
 
 const bySymbol = (a, b) => a.toString() > b.toString() ? 1 : -1;
 const getComposerTypes = comps => comps.map(c => c.composerType).sort(bySymbol);
+const excludeComposer = (composers, toExclude) => {
+	return composers.filter((composer) => composer !== toExclude);
+};
 
 const assertBeforeSendMsg = curry((beforeSendMsgFn, logStub, chainData, substring) => {
 	logStub.resetHistory();
@@ -13,12 +16,13 @@ const assertBeforeSendMsg = curry((beforeSendMsgFn, logStub, chainData, substrin
 
 	assert.ok(
 		beforeSendMsgLog.includes(substring),
-		`Substring "${substring}" should be found in beforeSendMsg log: "${beforeSendMsgLog}"`
+		`Substring "${substring}" should be found in beforeSendMsg log: "${beforeSendMsgLog}"`,
 	);
 });
 
 module.exports = {
 	bySymbol,
 	getComposerTypes,
+	excludeComposer,
 	assertBeforeSendMsg,
 };

package/lib/utils/testHelpers/testInputError.js

@@ -13,5 +13,30 @@ const commonTestInputError = curry((asserter, fn, args = [], expect = {}, msg) =
 	}, msg || `Invalid error if ${args.length ? args.map(JSON.stringify).join(', ') : 'no args'}`);
 });
 
+const suitestInvalidInputError = (message) => {
+	return new SuitestError(message, SuitestError.INVALID_INPUT);
+};
+
+/**
+ * @deprecated use assert.rejects and suitestInvalidInputError  https://nodejs.org/api/assert.html#assertrejectsasyncfn-error-message
+ * @example
+ * // Before:
+ * await testInputErrorAsync(testingFunc, ['some arg']);
+ * await testInputErrorAsync(testingFunc, ['some arg'] {message: 'Error message'});
+ * // After:
+ * await assert.rejects(() => testingFunc('some arg'));
+ * await assert.rejects(() => testingFunc('some arg'), suitestInvalidInputError('Error message'));
+ */
 module.exports.testInputErrorAsync = commonTestInputError(assertThrowsAsync);
+/**
+ * @deprecated use assert.throws instead https://nodejs.org/api/assert.html#assertthrowsfn-error-message
+ * @example
+ * // Before:
+ * await testInputErrorSync(testingFunc, ['some arg']);
+ * await testInputErrorSync(testingFunc, ['some arg'], {message: 'Error message'});
+ * // After:
+ * await assert.throws(() => testingFunc('some arg'));
+ * await assert.throws(() => testingFunc('some arg'), suitestInvalidInputError('Error message'));
+ */
 module.exports.testInputErrorSync = commonTestInputError(assert.throws);
+module.exports.suitestInvalidInputError = suitestInvalidInputError;

package/lib/validation/jsonSchemas.js

@@ -20,6 +20,8 @@ const LAUNCH_MODE = require('../constants/launchMode');
 const COOKIE_PROP = require('../constants/cookieProp');
 const OCR_READ_AS = require('../constants/ocrReadAs');
 const OCR_COLOR = require('../constants/ocrColor');
+const ACCURACY = require('../constants/accuracy');
+const LANG = require('../constants/lang');
 const schemas = {};
 
 const nonNegativeNumber = () => ({
@@ -32,6 +34,21 @@ const positiveNumber = () => ({
 	exclusiveMinimum: 0,
 });
 
+/**
+ * @description schema for validation region for OCR and Image assertions
+ */
+const regionSchema = () => ({
+	'type': 'array',
+	'items': [
+		{...nonNegativeNumber(), maximum: 100},
+		{...nonNegativeNumber(), maximum: 100},
+		{...positiveNumber(), maximum: 100},
+		{...positiveNumber(), maximum: 100},
+	],
+	'minItems': 4,
+	'additionalItems': false,
+});
+
 const CONFIG_OVERRIDE_PROPERTIES = {
 	'url': {'type': 'string'},
 	'suitestify': {'type': 'boolean'},
@@ -535,17 +552,7 @@ schemas[validationKeys.OCR_COMPARATORS] = {
 			},
 			'whitelist': schemas[validationKeys.NON_EMPTY_STRING],
 			'blacklist': schemas[validationKeys.NON_EMPTY_STRING],
-			'region': {
-				'type': 'array',
-				'items': [
-					{...nonNegativeNumber(), maximum: 100},
-					{...nonNegativeNumber(), maximum: 100},
-					{...positiveNumber(), maximum: 100},
-					{...positiveNumber(), maximum: 100},
-				],
-				'minItems': 4,
-				'additionalItems': false,
-			},
+			'region': regionSchema(),
 		},
 	},
 };
@@ -575,21 +582,43 @@ schemas[validationKeys.OCR_OPTIONS] = {
 			},
 			'whitelist': schemas[validationKeys.NON_EMPTY_STRING],
 			'blacklist': schemas[validationKeys.NON_EMPTY_STRING],
-			'region': {
-				'type': 'array',
-				'items': [
-					{...nonNegativeNumber(), maximum: 100},
-					{...nonNegativeNumber(), maximum: 100},
-					{...positiveNumber(), maximum: 100},
-					{...positiveNumber(), maximum: 100},
-				],
-				'minItems': 4,
-				'additionalItems': false,
-			},
+			'region': regionSchema(),
 		},
 	},
 };
 
+schemas[validationKeys.REGION] = {
+	'schemaId': validationKeys.REGION,
+	...regionSchema(),
+};
+
+schemas[validationKeys.IMAGE_DATA] = {
+	'schemaId': validationKeys.IMAGE_DATA,
+	'type': 'object',
+	'properties': {
+		'url': {'type': 'string'},
+		'filepath': {'type': 'string'},
+		'apiId': {'type': 'string'},
+	},
+	'anyOf': [
+		{'required': ['url']},
+		{'required': ['filepath']},
+		{'required': ['apiId']},
+	],
+};
+
+schemas[validationKeys.LANGUAGE] = {
+	'schemaId': validationKeys.LANGUAGE,
+	'type': 'string',
+	'enum': Object.values(LANG),
+};
+
+schemas[validationKeys.ACCURACY] = {
+	'schemaId': validationKeys.ACCURACY,
+	'type': 'string',
+	'enum': Object.values(ACCURACY),
+};
+
 Object.freeze(schemas);
 
 module.exports = schemas;

package/lib/validation/validators.js

@@ -245,6 +245,7 @@ const allowedUntilConditionChainTypes = [
 	'network',
 	'video',
 	'psVideo',
+	'image',
 ];
 
 const allowedUntilConditionChainNames = [
@@ -256,6 +257,7 @@ const allowedUntilConditionChainNames = [
 	'networkRequest',
 	'video',
 	'psVideo',
+	'image',
 ];
 
 const getSubjectType = path(['request', 'condition', 'subject', 'type']);

package/lib/validation/validatorsMap.js

@@ -111,6 +111,18 @@ const validatorsMap = {
 	[validationKeys.OCR_OPTIONS]: (value, text) => {
 		return validators.validateJsonSchema(validationKeys.OCR_OPTIONS, value, text);
 	},
+	[validationKeys.IMAGE_DATA]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.IMAGE_DATA, value, text);
+	},
+	[validationKeys.REGION]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.REGION, value, text);
+	},
+	[validationKeys.LANGUAGE]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.LANGUAGE, value, text);
+	},
+	[validationKeys.ACCURACY]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.ACCURACY, value, text);
+	},
 };
 
 Object.freeze(validatorsMap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suitest-js-api",
-  "version": "3.12.2",
+  "version": "3.14.0",
   "main": "index.js",
   "repository": "git@github.com:SuitestAutomation/suitest-js-api.git",
   "author": "Suitest <hello@suite.st>",
@@ -25,7 +25,10 @@
     "XClass TV testing",
     "Xumo testing",
     "Smart TV test automation",
-    "Fire TV test automation"
+    "Fire TV test automation",
+    "visual testing",
+    "image template matching",
+    "ocr"
   ],
   "homepage": "https://suite.st/",
   "license": "MIT",
@@ -91,7 +94,7 @@
   },
   "dependencies": {
     "@suitest/smst-to-text": "^4.13.0",
-    "@suitest/translate": "^4.15.0",
+    "@suitest/translate": "^4.16.0",
     "@types/node": "^14.0.10",
     "ajv": "^6.12.2",
     "ansi-regex": "^5.0.0",

package/suitest.js

@@ -40,6 +40,7 @@ const playstationVideoFactory = require('./lib/chains/playstationVideoChain');
 const setScreenOrientationFactory = require('./lib/chains/setScreenOrientationChain');
 const openDeepLinkFactory = require('./lib/chains/openDeepLinkChain');
 const ocrFactory = require('./lib/chains/ocrChain');
+const imageFactory = require('./lib/chains/imageChain');
 
 // Constants
 const {ELEMENT_PROP, VALUE} = require('./lib/constants/element');
@@ -62,6 +63,8 @@ const SCREEN_ORIENTATION = require('./lib/constants/screenOrientation');
 const COOKIE_PROP = require('./lib/constants/cookieProp');
 const OCR_READ_AS = require('./lib/constants/ocrReadAs');
 const OCR_COLOR = require('./lib/constants/ocrColor');
+const ACCURACY = require('./lib/constants/accuracy');
+const LANG = require('./lib/constants/lang');
 
 // Network
 const webSocketsFactory = require('./lib/api/webSockets');
@@ -139,6 +142,7 @@ class SUITEST_API extends EventEmitter {
 		const {setScreenOrientation, setScreenOrientationAssert} = setScreenOrientationFactory(this);
 		const {openDeepLink, openDeepLinkAssert} = openDeepLinkFactory(this);
 		const {ocr, ocrAssert} = ocrFactory(this);
+		const {image, imageAssert} = imageFactory(this);
 
 		this.openApp = openApp;
 		this.closeApp = closeApp;
@@ -167,6 +171,7 @@ class SUITEST_API extends EventEmitter {
 		this.setScreenOrientation = setScreenOrientation;
 		this.openDeepLink = openDeepLink;
 		this.ocr = ocr;
+		this.image = image;
 
 		this.PROP = ELEMENT_PROP;
 		this.COMP = PROP_COMPARATOR;
@@ -190,6 +195,8 @@ class SUITEST_API extends EventEmitter {
 		this.COOKIE_PROP = COOKIE_PROP;
 		this.OCR_READ_AS = OCR_READ_AS;
 		this.OCR_COLOR = OCR_COLOR;
+		this.ACCURACY = ACCURACY;
+		this.LANG = LANG;
 
 		this.assert = {
 			application: applicationAssert,
@@ -218,6 +225,7 @@ class SUITEST_API extends EventEmitter {
 			setScreenOrientation: setScreenOrientationAssert,
 			openDeepLink: openDeepLinkAssert,
 			ocr: ocrAssert,
+			image: imageAssert,
 		};
 
 		// Listen to process events to trigger websocket termination and dump warnings, if any

package/typeDefinition/ImageChain.d.ts

@@ -0,0 +1,47 @@
+import {
+	AbstractChain,
+	Timeout,
+	InRegionModifier,
+	VisibleModifier,
+	AccuracyModifier,
+	Negatable,
+	Assertable,
+	BaseEmptyChain,
+} from './modifiers';
+import {
+	AccuracyModifierNames,
+	AssertableMethodsNames,
+	InRegionMethodsNames,
+	NegatableMethodsNames,
+	TimeoutMethodsNames,
+	VisibleMethodsNames,
+	Chainable,
+	ChainWithoutMethods,
+} from './utils';
+
+interface ImageBase extends
+	// not(), doesNot(), isNot()
+	Negatable<ChainWithoutMethods<ImageBase, NegatableMethodsNames>>,
+	// timeout(...)
+	Timeout<ChainWithoutMethods<ImageBase, TimeoutMethodsNames>>,
+	// visible()
+	VisibleModifier<ChainWithoutMethods<ImageBase, VisibleMethodsNames>>,
+	// inRegion(...)
+	InRegionModifier<ChainWithoutMethods<ImageBase, InRegionMethodsNames>>,
+	// accuracy(...)
+	AccuracyModifier<ChainWithoutMethods<ImageBase, AccuracyModifierNames>>,
+	// toAssert(...)
+	Assertable<ChainWithoutMethods<ImageBase, AssertableMethodsNames>>,
+	// toString(), then(), abandon(), clone()
+	ImageBaseEvalChain<ImageBase>
+{}
+
+type ImageChain = Chainable<ImageBase>;
+
+interface ImageBaseEvalChain<TSelf> extends
+	BaseEmptyChain<TSelf, ImageEvalResult, ImageAbandonedChain>
+{}
+
+interface ImageAbandonedChain extends AbstractChain {}
+
+type ImageEvalResult = boolean;

package/typeDefinition/OcrChain.d.ts

@@ -3,17 +3,32 @@ import {
 	Assertable,
 	Timeout,
 	BaseEmptyChain,
+	Language,
 } from './modifiers';
 
+// +language +timeout
 export interface OcrChain extends
 	OcrBaseQueryChain<OcrChain>,
-	Timeout<OcrWithoutTimeout>
+	Timeout<OcrWithoutTimeout>,
+	Language<OcrWithoutLanguage>
 {}
 
+// -language +timeout
+interface OcrWithoutLanguage extends
+	Timeout<OcrEmptyChain>,
+	OcrBaseQueryChain<OcrWithoutLanguage>
+{}
+
+// + language -timeout
 interface OcrWithoutTimeout extends
+	Language<OcrEmptyChain>,
 	OcrBaseQueryChain<OcrWithoutTimeout>
 {}
 
+interface OcrEmptyChain extends
+	OcrBaseQueryChain<OcrEmptyChain>
+{}
+
 interface OcrBaseQueryChain<TSelf> extends
 	BaseEmptyChain<TSelf, OcrQueryResult, OcrAbandonedChain>,
 	Assertable<TSelf>

package/typeDefinition/constants/Accuracy.d.ts

@@ -0,0 +1,5 @@
+export type Accuracy = {
+	HIGH: 'high',
+	MEDIUM: 'medium',
+	LOW: 'low',
+};

package/typeDefinition/constants/Langs.d.ts

@@ -0,0 +1,9 @@
+export type Lang = {
+	ENGLISH: 'eng',
+	GERMAN: 'deu',
+	FRENCH: 'fra',
+	ITALIAN: 'ita',
+	DUTCH: 'nld',
+	SPANISH: 'spa',
+	POLISH: 'pol',
+};

package/typeDefinition/modifiers.d.ts

@@ -1,4 +1,7 @@
+import {ValueOf} from './utils';
 import {LaunchModeValues} from './constants/LaunchMode';
+import {Lang} from './constants/Langs';
+import {Accuracy} from './constants/Accuracy';
 
 export interface Thenable <R> {
 	then <U> (onFulfilled?: (value: R) => U | Thenable<U>, onRejected?: (error: any) => U | Thenable<U>): Thenable<U>;
@@ -264,3 +267,15 @@ export interface HandleModifier<T> {
 export interface GetAttributesModifier<T> {
 	getAttributes(attributes?: string[]): T;
 }
+
+export interface InRegionModifier<T> {
+	inRegion(region: [number, number, number, number]): T;
+}
+
+export interface Language<T> {
+	language(lang: ValueOf<Lang>): T;
+}
+
+export interface AccuracyModifier<T> {
+	accuracy(accuracy: ValueOf<Accuracy>): T;
+}

package/typeDefinition/utils/index.d.ts

@@ -1,6 +1,56 @@
+import {AccuracyModifier, Assertable, InRegionModifier, Negatable, Timeout, VisibleModifier} from '../modifiers';
+
 export type ValueOf<T> = T[keyof T];
 
 /**
  * @description utility type for checking that TObject is satisfies TSubject (aka satisfies operator)
  */
 export type Satisfies<TObject extends TSubject, TSubject> = TObject;
+
+/**
+ * @description utility type for converting given interface for describe suitest chains
+ * @example
+ *
+ * interface ExampleInterface {
+ *   method1: () => ChainWithoutMethods<ExampleInterface, 'method1'>;
+ *   method2: () => ChainWithoutMethods<ExampleInterface, 'method2'>;
+ *   method3: () => string;
+ * }
+ *
+ * type ChainableExample = Chainable<ExampleInterface>;
+ *
+ * declare const example: ChainableExample;
+ *
+ * example
+ *   .method1()
+ *   .method3(); // -> string will be returned
+ *
+ * example
+ *   .method1()
+ *   .method1(); // -> will be displayed error since method1 already called and no longer presents in chain
+ *
+ * example
+ *   .method1()
+ *   .method2()
+ *   .method2(); // -> will be displayed error since method2 already called and no longer presents in chain;
+ */
+export type Chainable<T> = {
+	[K in keyof T]: T[K] extends (...args: any[]) => ChainWithoutMethods<T, infer ExcludeMethods>
+		// if field is function than return new chain without specified methods names
+		? (...args: Parameters<T[K]>) => Chainable<WithoutMethods<T, ExcludeMethods>>
+		// will be returned as it is, if field not function or function which not return MethodToOmit helper type
+		: T[K];
+};
+
+export type WithoutMethods<T, K extends keyof T> = Omit<T, K>;
+
+export type ChainWithoutMethods<T, ExcludeMethods extends keyof T> = {
+	__excludeMethods: ExcludeMethods,
+}
+
+export type NegatableMethodsNames = keyof Negatable<any>;
+export type TimeoutMethodsNames = keyof Timeout<any>;
+export type VisibleMethodsNames = keyof VisibleModifier<any>;
+export type InRegionMethodsNames = keyof InRegionModifier<any>;
+export type AssertableMethodsNames = keyof Assertable<any>;
+export type AccuracyModifierNames = keyof AccuracyModifier<any>;