suitest-js-api 3.20.1 → 3.21.0

package/index.d.ts

@@ -60,15 +60,39 @@ export = suitest;
 
 declare namespace suitest {
 	export interface ISuitestBase extends NodeJS.EventEmitter {
-		openSession(options: OpenSessionOptions): Promise<OpenSessionResult|SuitestError>;
-		closeSession(): Promise<object|SuitestError>;
-		setAppConfig(configId: string, options?: ConfigOverride): Promise<void|SuitestError>;
-		pairDevice(deviceId: string, recordingSettings?: {recording?: 'autostart' | 'manualstart' | 'none', webhookUrl?: string}): Promise<DeviceData|SuitestError>;
-		releaseDevice(): Promise<void|SuitestError>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		openSession(options: OpenSessionOptions): Promise<OpenSessionResult>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		closeSession(): Promise<void>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		setAppConfig(configId: string, options?: ConfigOverride): Promise<void>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		pairDevice(deviceId: string, recordingSettings?: {recording?: 'autostart' | 'manualstart' | 'none', webhookUrl?: string}): Promise<DeviceData>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		releaseDevice(): Promise<void>;
 		startREPL(options?: ReplOptions): Promise<void>;
-		getAppConfig(): Promise<AppConfiguration|SuitestError>;
-		startRecording({webhookUrl}?: {webhookUrl: string}): Promise<string|SuitestError>;
-		stopRecording({discard}?: {discard: boolean}): Promise<void|SuitestError>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		getAppConfig(): Promise<AppConfiguration>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		startRecording({webhookUrl}?: {webhookUrl: string}): Promise<string | undefined>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		stopRecording({discard}?: {discard: boolean}): Promise<void>;
 
 		// config
 		getConfig(): ConfigureOptions;
@@ -267,7 +291,7 @@ declare namespace suitest {
 		id: string;
 		firmware: string;
 		modelId: string;
-		recordingUrl: string;
+		recordingUrl?: string;
 	}
 
 	interface ConfigOverride {
@@ -324,17 +348,31 @@ declare namespace suitest {
 	}
 
 	interface AuthContext {
-		headers: object;
+		headers: Record<string, string>;
 		tokenKey: string;
 
 		setContext(newContext: symbol, tokenId: string|undefined, tokenPassword: string|undefined): void;
 		clear(): void;
-		authorizeHttp(requestKey: string, requestObject: object, errorOptions: SuitestErrorOptions): Promise<SuitestError|object>;
-		authorizeWs(contentObject: object, commandName: string): Promise<SuitestError|object>;
-		authorizeWsConnection(connectObject: object, commandName: string): Promise<SuitestError|object>;
+
+		/**
+		 * @throws {SuitestError}
+		 */
+		authorizeHttp<T extends object>(requestkey: string, requestObject: T, errorOptions?: SuitestErrorOptions): Promise<WithHeaders<T>>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		authorizeWs<T extends object>(contentObject: T, commandName: string): Promise<T>;
+		/**
+		 * @throws {SuitestError}
+		 */
+		authorizeWsConnection<T extends object>(connectObject: T, commandName: string): Promise<WithHeaders<T>>;
 		getToken(): string;
 	}
 
+	type WithHeaders<T extends object> = T & {
+		headers: Record<string, string>
+	}
+
 	interface SuitestErrorOptions {
 		commandName?: string;
 		type?: string;

package/lib/chains/imageChain.js

@@ -12,6 +12,7 @@ const {
 	notComposer,
 	inRegionComposer,
 	accuracyComposer,
+	onScreenComposer,
 } = require('../composers');
 const makeChain = require('../utils/makeChain');
 const {getRequestType} = require('../utils/socketChainHelper');
@@ -102,6 +103,7 @@ const imageChainFactory = (classInstance) => {
 			thenComposer,
 			cloneComposer,
 			toJSONComposer,
+			onScreenComposer,
 		];
 
 		if (!data.isAssert) {

package/lib/commands/pairDevice.js

@@ -19,15 +19,15 @@ const SuitestError = require('../utils/SuitestError');
 
 /**
  * Pair with device
- * @param {Object} instance - main class instance
+ * @param {suitest.ISuitest} instance - main class instance
  * @param {string} deviceId - device to connect to
- * @param {Object | undefined} recordingSettings - {recording, webhookUrl} object. Optional.
- * @returns {ChainablePromise.<DeviceData>}
+ * @param {{recording?: 'autostart' | 'manualstart' | 'none', webhookUrl?: string}} [recordingSettings]
+ * @returns {Promise<DeviceData>}
  */
 async function pairDevice(
 	{webSockets, authContext, logger, pairedDeviceContext, config},
 	deviceId,
-	recordingSettings
+	recordingSettings,
 ) {
 	// validate deviceId string to be in uuid format
 	validate(validators.UUID, deviceId, invalidInputMessage(pairDevice.name, 'Device id'));

package/lib/commands/releaseDevice.js

@@ -10,8 +10,8 @@ const {disconnectedFromDevice, disconnectingFromDevice} = require('../texts');
 
 /**
  * Release paired device
- * @param {Object} instance of main class
- * @returns {ChainablePromise.<void>}
+ * @param {suitest.ISuitest} instance of main class
+ * @returns {Promise<void>}
  */
 async function releaseDevice({webSockets, authContext, pairedDeviceContext, logger}) {
 	logger.delayed(disconnectingFromDevice());

package/lib/commands/setAppConfig.js

@@ -9,10 +9,10 @@ const {invalidInputMessage, usingAppConfig, usedAppConfig, useAppConfigOverrides
 
 /**
  * Set application config
- * @param {Object} instance of main class
+ * @param {suitest.ISuitest} instance of main class
  * @param {string} configId - config Id
- * @param {Object} [configOverride] - an optional override of the configuration
- * @returns {Promise<*>}
+ * @param {suitest.ConfigOverride} [configOverride] - an optional override of the configuration
+ * @returns {Promise<void>}
  */
 async function setAppConfig({appContext, authContext, webSockets, logger}, configId, configOverride = {}) {
 	// validate input

package/lib/commands/startRecording.js

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

package/lib/commands/stopRecording.js

@@ -8,8 +8,9 @@ const {stopRecordingMessage} = require('../texts');
 
 /**
  * Stop recording
- * @param {SUITEST_API} instance of main class
- * @returns {ChainablePromise.<void>}
+ * @param {suitest.ISuitest} instance of main class
+ * @param {{discard: boolean}} [recordingSettings]
+ * @returns {Promise<void>}
  */
 async function stopRecording({webSockets, authContext, logger}, recordingSettings) {
 	const discard = recordingSettings ? recordingSettings.discard : false;

package/lib/composers/index.js

@@ -49,6 +49,7 @@ const withPropertiesComposer = require('./withPropertiesComposer');
 const inRegionComposer = require('./inRegionComposer');
 const languageComposer = require('./languageComposer');
 const {accuracyComposer} = require('./accuracyComposer');
+const onScreenComposer = require('./onScreenComposer');
 
 module.exports = {
 	abandonComposer,
@@ -104,4 +105,5 @@ module.exports = {
 	inRegionComposer,
 	languageComposer,
 	accuracyComposer,
+	onScreenComposer,
 };

package/lib/composers/onScreenComposer.js

@@ -0,0 +1,14 @@
+const {makeModifierComposer} = require('../utils/makeComposer');
+const composers = require('../constants/composer');
+
+const onScreenComposer = makeModifierComposer(composers.ON_SCREEN, ['onScreen'], (_, meta) => {
+	const newMetaData = {...meta};
+
+	if ('region' in newMetaData) {
+		delete newMetaData.region;
+	}
+
+	return newMetaData;
+});
+
+module.exports = onScreenComposer;

package/lib/constants/composer.js

@@ -49,6 +49,7 @@ const composers = {
 	IN_REGION:        Symbol('inRegion'),
 	LANGUAGE:         Symbol('language'),
 	ACCURACY:         Symbol('accuracy'),
+	ON_SCREEN:        Symbol('onScreen'),
 };
 
 Object.freeze(composers);

package/lib/utils/AuthContext.js

@@ -56,9 +56,11 @@ const allowedRequests = {
 
 /**
  * Decorate http requestObject with current context headers
- * @param {*} requestObject
- * @param {*} headers
- * @returns requestObject decorated with auth headers
+ * @template T
+ * @template U
+ * @param {T} requestObject
+ * @param {U} headers
+ * @returns {T & {headers: U}} requestObject decorated with auth headers
  */
 function decorateRequestObject(requestObject, headers) {
 	return Object.assign({}, requestObject, {headers});
@@ -128,10 +130,12 @@ class AuthContext extends Context {
 	/**
 	 * Check if http request is allowed based on request key and current context.
 	 * Decorate request object if allowed.
+	 * @template T
 	 * @param {string} requestKey
-	 * @param {*} requestObject
+	 * @param {T} requestObject
 	 * @param {SuitestErrorOptions} errorOptions - function name which will be invoked by user.
-	 * @returns {Promise}
+	 * @throws {SuitestError} if request is not allowed.
+	 * @returns {Promise<T & {headers: Record<string, string>}>}
 	 */
 	authorizeHttp(requestKey, requestObject, errorOptions = {}) {
 		if (
@@ -146,9 +150,11 @@ class AuthContext extends Context {
 
 	/**
 	 * Check if ws request is allowed based on content type and current context.
-	 * @param {*} contentObject
+	 * @template T
+	 * @param {T} contentObject
 	 * @param {string} commandName - function name which will be invoked by user.
-	 * @returns {Promise}
+	 * @throws {SuitestError} if request is not allowed.
+	 * @returns {Promise<T>}
 	 */
 	authorizeWs(contentObject, commandName) {
 		if (contentObject && allowedRequests.ws[super.context].includes(contentObject.type)) { // check if ws content type is allowed
@@ -160,9 +166,11 @@ class AuthContext extends Context {
 
 	/**
 	 * Check if ws connection is allowed based on current context.
-	 * @param {*} connectObject
+	 * @template T
+	 * @param {T} connectObject
 	 * @param {string} commandName - function name which will be invoked by user.
-	 * @returns {Promise}
+	 * @throws {SuitestError} if request is not allowed.
+	 * @returns {Promise<T & {headers: Record<string, string>}>}
 	 */
 	authorizeWsConnection(connectObject, commandName) {
 		if (super.context !== sessionConstants.GUEST) {

package/lib/validation/jsonSchemas.js

@@ -49,6 +49,18 @@ const regionSchema = () => ({
 	'additionalItems': false,
 });
 
+const regionWithNullableValuesSchema = () => ({
+	'type': 'array',
+	'items': [
+		{type: ['number', 'null'], minimum: 0, maximum: 100},
+		{type: ['number', 'null'], minimum: 0, maximum: 100},
+		{type: ['number', 'null'], exclusiveMinimum: 0, maximum: 100},
+		{type: ['number', 'null'], exclusiveMinimum: 0, maximum: 100},
+	],
+	'minItems': 4,
+	'additionalItems': false,
+});
+
 const CONFIG_OVERRIDE_PROPERTIES = {
 	'url': {'type': 'string'},
 	'suitestify': {'type': 'boolean'},
@@ -594,7 +606,7 @@ schemas[validationKeys.OCR_OPTIONS] = {
 
 schemas[validationKeys.REGION] = {
 	'schemaId': validationKeys.REGION,
-	...regionSchema(),
+	...regionWithNullableValuesSchema(),
 };
 
 schemas[validationKeys.IMAGE_DATA] = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suitest-js-api",
-  "version": "3.20.1",
+  "version": "3.21.0",
   "main": "index.js",
   "repository": "git@github.com:SuitestAutomation/suitest-js-api.git",
   "author": "Suitest <hello@suite.st>",
@@ -90,11 +90,11 @@
     "nock": "^12.0.3",
     "nyc": "15.1.0",
     "sinon": "^9.0.2",
-    "typescript": "4.9.4"
+    "typescript": "5.8.3"
   },
   "dependencies": {
     "@suitest/smst-to-text": "^4.13.0",
-    "@suitest/translate": "^4.22.0",
+    "@suitest/translate": "^4.24.0",
     "@types/node": "^14.0.10",
     "ajv": "^6.12.2",
     "ansi-regex": "^5.0.0",

package/typeDefinition/ImageChain.d.ts

@@ -7,6 +7,7 @@ import {
 	Negatable,
 	Assertable,
 	BaseEmptyChain,
+	OnScreenModifier,
 } from './modifiers';
 import {
 	AccuracyModifierNames,
@@ -17,6 +18,7 @@ import {
 	VisibleMethodsNames,
 	Chainable,
 	ChainWithoutMethods,
+	OnScreenModifierNames,
 } from './utils';
 
 interface ImageBase extends
@@ -28,6 +30,8 @@ interface ImageBase extends
 	VisibleModifier<ChainWithoutMethods<ImageBase, VisibleMethodsNames>>,
 	// inRegion(...)
 	InRegionModifier<ChainWithoutMethods<ImageBase, InRegionMethodsNames>>,
+	// onScreen()
+	OnScreenModifier<ChainWithoutMethods<ImageBase, OnScreenModifierNames>>,
 	// accuracy(...)
 	AccuracyModifier<ChainWithoutMethods<ImageBase, AccuracyModifierNames>>,
 	// toAssert(...)

package/typeDefinition/modifiers.d.ts

@@ -273,7 +273,7 @@ export interface GetAttributesModifier<T> {
 }
 
 export interface InRegionModifier<T> {
-	inRegion(region: [number, number, number, number]): T;
+	inRegion(region: [number | null, number | null, number | null, number | null]): T;
 }
 
 export interface Language<T> {
@@ -283,3 +283,7 @@ export interface Language<T> {
 export interface AccuracyModifier<T> {
 	accuracy(accuracy: ValueOf<Accuracy>): T;
 }
+
+export interface OnScreenModifier<T> {
+	onScreen(): T;
+}

package/typeDefinition/utils/index.d.ts

@@ -1,4 +1,4 @@
-import {AccuracyModifier, Assertable, InRegionModifier, Negatable, Timeout, VisibleModifier} from '../modifiers';
+import {AccuracyModifier, Assertable, InRegionModifier, Negatable, Timeout, VisibleModifier, OnScreenModifier} from '../modifiers';
 
 export type ValueOf<T> = T[keyof T];
 
@@ -54,3 +54,4 @@ export type VisibleMethodsNames = keyof VisibleModifier<any>;
 export type InRegionMethodsNames = keyof InRegionModifier<any>;
 export type AssertableMethodsNames = keyof Assertable<any>;
 export type AccuracyModifierNames = keyof AccuracyModifier<any>;
+export type OnScreenModifierNames = keyof OnScreenModifier<any>;