suitest-js-api 3.11.7 → 3.12.0

package/README.md

@@ -45,6 +45,7 @@ Vizio etc.
 - Locally installed Chrome, Firefox, Safari and Edge
 - Apple tvOS, iOS and iPadOS devices, including simulators
 - Roku TVs, boxes and sticks
+- Xfinity, XClass, Xumo and Sky devices
 
 Suitest supports automating end-to-end testing of:
 
@@ -57,8 +58,11 @@ Suitest supports automating end-to-end testing of:
 - Xbox One and Xbox Series S and X apps
 - PlayStation 4 / 5 apps
 - Roku apps
+- Sky apps
 - VIDAA apps
 - Vizio SmartCast apps
+- Xfinity / XClass TV / Xumo TV apps
+- Xumo (Entertainment OS) apps
 - Traditional websites and web apps for desktop browsers.
 
 ## Contributing

package/index.d.ts

@@ -42,6 +42,11 @@ import {RelativePosition} from './typeDefinition/RelativePositionChain';
 import {LaunchMode} from './typeDefinition/constants/LaunchMode';
 import {OpenDeepLinkChain} from './typeDefinition/OpenDeepLink';
 import {CookieProp} from './typeDefinition/constants/CookieProp';
+import {OcrChain} from './typeDefinition/OcrChain';
+import {OcrReadAs} from './typeDefinition/constants/OcrReadAs';
+import {StringPropComparators} from './typeDefinition/constants/PropComparators';
+import {ValueOf} from './typeDefinition/utils';
+import {OcrColor} from './typeDefinition/constants/OcrColor';
 
 // --------------- Suitest Interface ---------------------- //
 
@@ -120,6 +125,7 @@ declare namespace suitest {
 		 */
 		saveScreenshot(fileName?: string): TakeScreenshotChain<void>;
 		openDeepLink(deepLink?: string): OpenDeepLinkChain;
+		ocr(comparators: OcrCommonItem[]): OcrChain;
 
 		getPairedDevice(): null | {
 			deviceId: string,
@@ -157,6 +163,8 @@ declare namespace suitest {
 		SCREEN_ORIENTATION: ScreenOrientation;
 		LAUNCH_MODE: LaunchMode;
 		COOKIE_PROP: CookieProp;
+		OCR_READ_AS: OcrReadAs;
+		OCR_COLOR: OcrColor;
 
 		authContext: AuthContext;
 		appContext: Context;
@@ -203,6 +211,7 @@ declare namespace suitest {
 		window(): WindowChain;
 		setScreenOrientation(orientation: ScreenOrientationValues): SetScreenOrientationChain;
 		openDeepLink(deepLink?: string): OpenDeepLinkChain;
+		ocr(comparators: OcrCommonItem[]): OcrChain;
 	}
 
 	type NetworkLogEvent = {
@@ -336,4 +345,15 @@ declare namespace suitest {
 		| 'portraitReversed'
 		| 'landscape'
 		| 'landscapeReversed';
+
+	type OcrCommonItem = {
+		val: string,
+		type?: StringPropComparators,
+		readAs?: ValueOf<OcrReadAs>,
+		align?: boolean,
+		color?: ValueOf<OcrColor>,
+		whitelist?: string,
+		blacklist?: string,
+		region?: [x: number, y: number, width: number, height: number],
+	}
 }

package/lib/chains/ocrChain.js

@@ -0,0 +1,144 @@
+const {
+	makeToStringComposer,
+	makeThenComposer,
+	makeToJSONComposer,
+	cloneComposer,
+	assertComposer,
+	abandonComposer,
+	timeoutComposer,
+} = require('../composers');
+const makeChain = require('../utils/makeChain');
+const {getRequestType} = require('../utils/socketChainHelper');
+const {validate, validators} = require('../validation');
+const {invalidInputMessage, assertOcrMalformed} = require('../texts');
+const {applyTimeout} = require('../utils/chainUtils');
+const SuitestError = require('../utils/SuitestError');
+const {PROP_COMPARATOR} = require('../constants/comparator');
+
+const validateOcrOptions = (ocrOptions) => {
+	return ocrOptions === undefined ? undefined : validate(
+		validators.OCR_OPTIONS,
+		ocrOptions,
+		invalidInputMessage('ocr', 'OCR data'),
+	);
+};
+
+const validateOcrComparators = (ocrComparators) => {
+	if (!Array.isArray(ocrComparators) || ocrComparators.length === 0) {
+		throw new SuitestError(assertOcrMalformed(), SuitestError.INVALID_INPUT);
+	}
+
+	return validate(
+		validators.OCR_COMPARATORS,
+		ocrComparators,
+		invalidInputMessage('ocr', 'OCR data'),
+	);
+};
+
+/**
+ * @description return copy of passed ocr comparator with default "type" property
+ * @param {import('../../index.d.ts').OcrCommonItem} ocrItem
+ * @returns {import('../../index.d.ts').OcrCommonItem}
+ */
+const ocrItemWithDefaultType = (ocrItem) => {
+	const ocrItemCopy = {...ocrItem};
+
+	if (ocrItemCopy.val !== undefined) {
+		ocrItemCopy.type = ocrItemCopy.type || PROP_COMPARATOR.EQUAL;
+	}
+
+	return ocrItemCopy;
+};
+
+/**
+ * @param {import('../../index.d.ts').ISuitest} classInstance
+ */
+const ocrFactory = (classInstance) => {
+	const toJSON = (data) => {
+		const subject = {type: 'ocr'};
+		const socketMessage = {type: getRequestType(data)};
+
+		if (socketMessage.type === 'query') {
+			socketMessage.subject = subject;
+			if (data.ocrItems) {
+				socketMessage.subject.options = data.ocrItems;
+			}
+		} else {
+			socketMessage.request = applyTimeout(
+				{
+					type: 'assert',
+					condition: {
+						subject,
+						type: 'ocrComparators',
+					},
+				},
+				data,
+				classInstance.config.defaultTimeout,
+			);
+			if (data.ocrItems) {
+				socketMessage.request.condition.comparators = validateOcrComparators(data.ocrItems);
+			}
+		}
+
+		return socketMessage;
+	};
+
+	const toStringComposer = makeToStringComposer(toJSON);
+	const thenComposer = makeThenComposer(toJSON);
+	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.timeout) {
+			output.push(timeoutComposer);
+		}
+
+		return output;
+	};
+
+	const makeOcrChain = (ocrItems) => {
+		return makeChain(
+			classInstance,
+			getComposers,
+			{
+				type: 'ocr',
+				ocrItems,
+			},
+		);
+	};
+
+	return {
+		ocr: (ocrOptions) => {
+			const validatedOcrOptions = validateOcrOptions(ocrOptions);
+			const processedOcrOptions = validatedOcrOptions && validatedOcrOptions.map(ocrItemWithDefaultType);
+
+			return makeOcrChain(processedOcrOptions);
+		},
+		ocrAssert: (ocrComparators) => {
+			const validatedOcrComparators = validateOcrComparators(ocrComparators);
+			const processedOcrComparators = validatedOcrComparators.map(ocrItemWithDefaultType);
+
+			return makeOcrChain(processedOcrComparators).toAssert();
+		},
+
+		// for unit tests
+		getComposers,
+		toJSON,
+	};
+};
+
+module.exports = ocrFactory;

package/lib/constants/ocrColor.js

@@ -0,0 +1,8 @@
+const OCR_COLOR = {
+	DARK: 'dark',
+	LIGHT: 'light',
+};
+
+Object.freeze(OCR_COLOR);
+
+module.exports = OCR_COLOR;

package/lib/constants/ocrReadAs.js

@@ -0,0 +1,9 @@
+const OCR_READ_AS = {
+	LINE: 'single-line',
+	WORD: 'single-word',
+	BLOCK: 'single-block',
+};
+
+Object.freeze(OCR_READ_AS);
+
+module.exports = OCR_READ_AS;

package/lib/constants/validationKeys.js

@@ -33,6 +33,8 @@ const validationKeys = {
 	ELEMENT_HANDLE: Symbol('handle'),
 	ELEMENT_ATTRIBUTES: Symbol('getAttributes'),
 	COOKIE_PROPS: Symbol('cookieProps'),
+	OCR_COMPARATORS: Symbol('ocrComparators'),
+	OCR_OPTIONS: Symbol('ocrOptions'),
 };
 
 Object.freeze(validationKeys);

package/lib/texts.js

@@ -77,6 +77,7 @@ module.exports = {
 
 	positionIsMalformed: () => 'position command is malformed',
 	relativePositionIsMalformed: () => 'relative position is malformed',
+	assertOcrMalformed: () => 'Assert ocr line is malformed - comparators are missing',
 
 	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

@@ -59,7 +59,7 @@ const processServerResponse = (logger, verbosity) =>
 		}
 		// query
 		if (isQuery) {
-		// if one of query fields is on res, return it
+			// if one of query fields is on res, return it
 			const queryKeyFound = [
 				'cookieValue',
 				'cookieExists',
@@ -71,6 +71,7 @@ const processServerResponse = (logger, verbosity) =>
 				'attributes',
 				'execute',
 				'location',
+				'ocr',
 			].find(key => key in res);
 
 			if (queryKeyFound) {
@@ -170,7 +171,8 @@ const getRequestType = (data, hasQuery = true) => {
 		!data.isMoveTo &&
 		isNil(data.sendText) &&
 		isNil(data.setText) &&
-		isNil(data.properties)
+		isNil(data.properties) &&
+		isNil(data.comparators)
 	) {
 		return 'query';
 	}

package/lib/validation/jsonSchemas.js

@@ -18,8 +18,20 @@ const VRC = require('../constants/vrc');
 const SCREEN_ORIENTATION = require('../constants/screenOrientation');
 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 schemas = {};
 
+const nonNegativeNumber = () => ({
+	type: 'number',
+	minimum: 0,
+});
+
+const positiveNumber = () => ({
+	type: 'number',
+	exclusiveMinimum: 0,
+});
+
 const CONFIG_OVERRIDE_PROPERTIES = {
 	'url': {'type': 'string'},
 	'suitestify': {'type': 'boolean'},
@@ -498,6 +510,86 @@ schemas[validationKeys.COOKIE_PROPS] = {
 	},
 };
 
+// schema for validating OCR assertion (testLine) comparators
+schemas[validationKeys.OCR_COMPARATORS] = {
+	'schemaId': validationKeys.OCR_COMPARATORS,
+	'type': 'array',
+	'items': {
+		'type': 'object',
+		'dependencies': {
+			'type': ['val'],
+		},
+		'required': ['val'],
+		'additionalProperties': false,
+		'properties': {
+			'val': {'type': 'string'},
+			'type': stringComparators(),
+			'readAs': {
+				'type': 'string',
+				'enum': Object.values(OCR_READ_AS),
+			},
+			'align': {'type': 'boolean'},
+			'color': {
+				'type': 'string',
+				'enum': Object.values(OCR_COLOR),
+			},
+			'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,
+			},
+		},
+	},
+};
+
+// schema for validating OCR query options
+schemas[validationKeys.OCR_OPTIONS] = {
+	'schemaId': validationKeys.OCR_OPTIONS,
+	'type': 'array',
+	'items': {
+		'type': 'object',
+		'required': [],
+		'dependencies': {
+			'type': ['val'],
+		},
+		'additionalProperties': false,
+		'properties': {
+			'val': {'type': 'string'},
+			'type': stringComparators(),
+			'readAs': {
+				'type': 'string',
+				'enum': Object.values(OCR_READ_AS),
+			},
+			'align': {'type': 'boolean'},
+			'color': {
+				'type': 'string',
+				'enum': Object.values(OCR_COLOR),
+			},
+			'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,
+			},
+		},
+	},
+};
+
 Object.freeze(schemas);
 
 module.exports = schemas;

package/lib/validation/validators.js

@@ -109,6 +109,8 @@ function prettifyJsonSchemaErrors(validate) {
 			validationKeys.ELEMENT_ATTRIBUTES,
 			validationKeys.CSS_PROPS,
 			validationKeys.COOKIE_PROPS,
+			validationKeys.OCR_COMPARATORS,
+			validationKeys.OCR_OPTIONS,
 		].includes(validate.schema.schemaId)
 	) {
 		errors = validate.errors.map(err => {

package/lib/validation/validatorsMap.js

@@ -105,6 +105,12 @@ const validatorsMap = {
 	[validationKeys.COOKIE_PROPS]: (value, text) => {
 		return validators.validateJsonSchema(validationKeys.COOKIE_PROPS, value, text);
 	},
+	[validationKeys.OCR_COMPARATORS]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.OCR_COMPARATORS, value, text);
+	},
+	[validationKeys.OCR_OPTIONS]: (value, text) => {
+		return validators.validateJsonSchema(validationKeys.OCR_OPTIONS, value, text);
+	},
 };
 
 Object.freeze(validatorsMap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suitest-js-api",
-  "version": "3.11.7",
+  "version": "3.12.0",
   "main": "index.js",
   "repository": "git@github.com:SuitestAutomation/suitest-js-api.git",
   "author": "Suitest <hello@suite.st>",
@@ -18,8 +18,12 @@
     "Android TV testing",
     "Apple TV testing",
     "Roku testing",
+    "Sky testing",
     "VIDAA testing",
     "Vizio SmartCast testing",
+    "Xfinity testing",
+    "XClass TV testing",
+    "Xumo testing",
     "Smart TV test automation",
     "Fire TV test automation"
   ],
@@ -86,8 +90,8 @@
     "typescript": "4.9.4"
   },
   "dependencies": {
-    "@suitest/smst-to-text": "^4.9.0",
-    "@suitest/translate": "^4.12.0",
+    "@suitest/smst-to-text": "^4.13.0",
+    "@suitest/translate": "^4.15.0",
     "@types/node": "^14.0.10",
     "ajv": "^6.12.2",
     "ansi-regex": "^5.0.0",

package/suitest.js

@@ -39,6 +39,7 @@ const videoFactory = require('./lib/chains/videoChain');
 const playstationVideoFactory = require('./lib/chains/playstationVideoChain');
 const setScreenOrientationFactory = require('./lib/chains/setScreenOrientationChain');
 const openDeepLinkFactory = require('./lib/chains/openDeepLinkChain');
+const ocrFactory = require('./lib/chains/ocrChain');
 
 // Constants
 const {ELEMENT_PROP, VALUE} = require('./lib/constants/element');
@@ -59,6 +60,8 @@ const LAUNCH_MODE = require('./lib/constants/launchMode');
 const DIRECTIONS = require('./lib/constants/directions');
 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');
 
 // Network
 const webSocketsFactory = require('./lib/api/webSockets');
@@ -135,6 +138,7 @@ class SUITEST_API extends EventEmitter {
 		const {saveScreenshot} = saveScreenshotFactory(this);
 		const {setScreenOrientation, setScreenOrientationAssert} = setScreenOrientationFactory(this);
 		const {openDeepLink, openDeepLinkAssert} = openDeepLinkFactory(this);
+		const {ocr, ocrAssert} = ocrFactory(this);
 
 		this.openApp = openApp;
 		this.closeApp = closeApp;
@@ -162,6 +166,7 @@ class SUITEST_API extends EventEmitter {
 		this.saveScreenshot = saveScreenshot;
 		this.setScreenOrientation = setScreenOrientation;
 		this.openDeepLink = openDeepLink;
+		this.ocr = ocr;
 
 		this.PROP = ELEMENT_PROP;
 		this.COMP = PROP_COMPARATOR;
@@ -183,6 +188,8 @@ class SUITEST_API extends EventEmitter {
 		this.DIRECTIONS = DIRECTIONS;
 		this.SCREEN_ORIENTATION = SCREEN_ORIENTATION;
 		this.COOKIE_PROP = COOKIE_PROP;
+		this.OCR_READ_AS = OCR_READ_AS;
+		this.OCR_COLOR = OCR_COLOR;
 
 		this.assert = {
 			application: applicationAssert,
@@ -210,6 +217,7 @@ class SUITEST_API extends EventEmitter {
 			psVideo: playstationVideoAssert,
 			setScreenOrientation: setScreenOrientationAssert,
 			openDeepLink: openDeepLinkAssert,
+			ocr: ocrAssert,
 		};
 
 		// Listen to process events to trigger websocket termination and dump warnings, if any

package/typeDefinition/OcrChain.d.ts

@@ -0,0 +1,24 @@
+import {
+	AbstractChain,
+	Assertable,
+	Timeout,
+	BaseEmptyChain,
+} from './modifiers';
+
+export interface OcrChain extends
+	OcrBaseQueryChain<OcrChain>,
+	Timeout<OcrWithoutTimeout>
+{}
+
+interface OcrWithoutTimeout extends
+	OcrBaseQueryChain<OcrWithoutTimeout>
+{}
+
+interface OcrBaseQueryChain<TSelf> extends
+	BaseEmptyChain<TSelf, OcrQueryResult, OcrAbandonedChain>,
+	Assertable<TSelf>
+{}
+
+interface OcrAbandonedChain extends AbstractChain {}
+
+type OcrQueryResult = string[];

package/typeDefinition/constants/OcrColor.d.ts

@@ -0,0 +1,4 @@
+export type OcrColor = {
+	DARK: 'dark',
+	LIGHT: 'light',
+};

package/typeDefinition/constants/OcrReadAs.d.ts

@@ -0,0 +1,5 @@
+export type OcrReadAs = {
+	LINE: 'single-line',
+	WORD: 'single-word',
+	BLOCK: 'single-block',
+}