@mablhq/mabl-cli 2.51.18 → 2.51.28

package/index.d.ts

@@ -145,19 +145,42 @@ export declare enum MobilePlatformEnum {
   Ios = 'ios',
 }
 
-// Playwright external tool types
-
+/**
+ * Options for the MablToolset
+ */
 export interface MablToolsetOptions {
+  /** an API key to use to authenticate the MablApiClient */
   apiKey: string;
+  /** A playwright browser context to use */
   browserContext?: BrowserContext;
+  /** The workspace ID to use with the mabl tools, if not supplied an API request will be attempted to determine the correct ID */
   workspaceId?: string;
+  /** The Playwright test */
   test: TestType<any, any>;
 }
 
+/**
+ * The response from the gen AI assertion.
+ */
 export interface GenAiAssertionResponse {
+  /**
+   * Whether the assertion passed or failed
+   */
   success: boolean;
+  /**
+   * The explanation for the assertion
+   */
   explanation?: string;
+  /**
+   * The summary of the assertion
+   */
+  summary?: string;
+  /**
+   * The criteria for the assertion
+   */
+  assertionCriteria?: string[];
 }
+
 export interface DatabaseQueryParameter {
   id?: string;
   type: 'String' | 'Number' | 'Boolean';
@@ -183,24 +206,73 @@ export interface DatabaseQueryResultSet {
   }>;
 }
 
+/**
+ * The MablToolset is set of mabl features that can be used in Playwright tests
+ */
 export interface MablToolset {
   constructor(options: MablToolsetOptions);
+
+  /**
+   * Evaluates a gen AI prompt against the current state of the browser or specified element and returns the result of the evaluation.
+   * @param page The page to evaluate the gen AI prompt against
+   * @param prompt The gen AI prompt to evaluate
+   * @param locator optional element to run the prompt against, the bounding box of the element will be used to produce the screenshot used in the assertion
+   * @returns
+   */
   evaluateGenAiAssertion(
-    // TODO this is any because it needs to align with the @playwright/test package's Page and we don't have that as a dependency of the CLI right now
-    page: any,
+    page: Page,
     prompt: string,
     locator?: Locator,
   ): Promise<GenAiAssertionResponse>;
+
+  /**
+   * Initializes the mabl tooling and execution context to work with the provided Playwright BrowserContext
+   * @param browserContext the Playwright BrowserContext to use with the MablTools
+   */
   initializeContext(browserContext: BrowserContext): Promise<void>;
+
+  /**
+   * Calls into the mabl API to create a new email address that can be used to receive emails during the external test run.
+   * @returns a new email address that can be used to receive emails
+   */
   createMailBoxAddress(): Promise<string>;
+
+  /**
+   * Run an email find action to locate an email that matches the provided email descriptor.
+   * @param emailAddress the email address to wait for
+   * @param page the page to wait for the email on
+   * @param emailFindOptions optional options to use in locating the email
+   * @returns a URL that can be used to open the email in a browser
+   */
   waitForEmail(
     emailAddress: string,
     page: Page | Frame,
     emailFindOptions?: EmailFindOptions,
   ): Promise<MablMailboxEmail>;
-  openEmailUrl(page: any, emailUrl: string): Promise<MablMailboxEmail>;
+
+  /**
+   * Get a the username/password from a mabl credential to use in a playwright test
+   * @param credentialId The ID of the credential to get
+   * @returns The username/password credential
+   */
   getCredentials(credentialsId: string): Promise<UsernamePasswordCredential>;
+
+  /**
+   * Get an MFA code for a credential
+   * @param credentialId The ID of the credential to get the MFA code for
+   * @returns The MFA code
+   */
   getMfaCode(credentialsId: string): Promise<string>;
+
+  /**
+   * Executes a database query
+   * @param dbConnectionId The ID of the database connection to use
+   * @param query The query to execute
+   * @param queryParameters Optional parameters to use in the query
+   * @param environmentId Optional environment ID to use in the query
+   * @param timeoutMillis Optional timeout in milliseconds for the query
+   * @returns The result of the query
+   */
   executeQuery(
     dbConnectionId: string,
     query: string,
@@ -208,6 +280,12 @@ export interface MablToolset {
     environmentId?: string,
     timeoutMillis?: number,
   ): Promise<DatabaseQueryResultSet>;
+
+  /**
+   * Opens a PDF file in the supplied Page for use in Playwright
+   * @param filePath The path to the PDF file to open
+   * @param page The page to open the PDF file in
+   */
   openPdfFile(filePath: string, page: Page): Promise<void>;
 }
 
@@ -247,16 +325,46 @@ export interface EmailFindOptions {
   timeoutMillis?: number;
 }
 
+/**
+ * A username and password credential
+ */
 export interface UsernamePasswordCredential {
+  /**
+   * The username for the credential
+   */
   username: string;
+  /**
+   * The password for the credential
+   */
   password: string;
 }
 
+/**
+ * A mailbox email
+ */
 export interface MablMailboxEmail {
-  open(): Promise<void>;
-  getToAddress(): Promise<string | null>;
-  getFromAddress(): Promise<string | null>;
-  getSubject(): Promise<string | null>;
-  getBodyText(): Promise<string | null>;
-  getBodyLocator(): Locator;
+  /**
+   * The URL to access to the email preview.
+   */
+  readonly emailUrl: string;
+  /**
+   * The page the email is on
+   */
+  readonly page: Page;
+  /**
+   * The locator in the email preview for the to address of the email.
+   */
+  readonly toAddress: Locator;
+  /**
+   * The locator for the subject of the email
+   */
+  readonly subject: Locator;
+  /**
+   * The locator in the email preview for the body of the email.
+   */
+  readonly body: Locator;
+  /**
+   * The locator in the email preview for the from address of the email.
+   */
+  readonly fromAddress: Locator;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mablhq/mabl-cli",
-  "version": "2.51.18",
+  "version": "2.51.28",
   "license": "SEE LICENSE IN LICENSE.txt",
   "description": "The official mabl command line interface tool",
   "main": "index.js",