maests/dist/commands/commands.mjs

An executable compiler for creating Maestro's yaml-flows with typescript.

import {
  tapOn,
  tapOnPoint,
  tapOnText,
  waitForAndTapOn
} from "./tap.mjs";
import { runFlow, runScript } from "./run.mjs";
import { clearState, initFlow, launchApp } from "./init.mjs";
import { repeat, repeatWhileVisible, repeatWhileNotVisible } from "./repeat.mjs";
import { assertNotVisible, assertTrue, assertVisible } from "./assert.mjs";
import { addMedia } from "./addMedia.mjs";
import { addOut } from "../out.mjs";
import {
  copyTextFrom,
  eraseText,
  inputRandomEmail,
  inputRandomName,
  inputRandomNumber,
  inputRandomText,
  inputText
} from "./text.mjs";
import { swipeDown, swipeLeft, swipeRight, swipeUp } from "./swipe.mjs";
import {
  wait,
  waitForAnimationEnd,
  waitUntilNotVisible,
  waitUntilVisible
} from "./wait.mjs";
const MaestroTranslators = {
  /**
   * Initializes the test flow with optional configuration.
   * @param config - Optional configuration with appId and other environment variables.
   */
  initFlow,
  /**
   * Launches the application with optional configuration settings.
   * @param config - Configuration options for appId, state clearing, keychain clearing, and app stopping.
   */
  launchApp,
  /**
   * Clears the state of the current app or the specified app by appId.
   * @param appId - Optional appId to clear state for a specific app.
   */
  clearState,
  runScript,
  /**
   * Runs a sub-flow defined by a path with optional environment variables.
   * @param path - The path to the sub-flow.
   * @param env - Optional map of environment variables for the sub-flow.
   */
  runFlow,
  /**
   * Taps on an element specified by a testId.
   * @param id - The testId of the target element.
   * @param props - Optional tap properties for customized tap behavior.
   */
  tapOn,
  /**
   * Taps on a visible text element on the screen.
   * @param text - The text to tap on.
   * @param props - Optional tap properties such as retries, repeat count, and timeout.
   */
  tapOnText,
  /**
   * Taps on a specific point on the screen.
   * @param point - Coordinates to tap, can use numbers (dips) or strings (percentages).
   * @param props - Optional tap properties.
   */
  tapOnPoint,
  /**
   * Waits for an element by testId to appear, then taps on it.
   * @param id - Required: The testId of the element to wait for and tap.
   * @param props - Properties for wait and tap actions, combining both WaitProps and TapProps.
   */
  waitForAndTapOn,
  /**
   * Clears the entire keychain.
   */
  clearKeychain: () => {
    addOut(`- clearKeychain
`);
  },
  /**
   * Performs a long press on an element identified by its testId.
   * @param id - The testId of the element to long press.
   */
  longPressOn: (id) => {
    addOut(`- longPressOn:
    id: "${id}"
`);
  },
  /**
   * Performs a long press on a specified point.
   * @param point - The x and y coordinates to long press.
   */
  longPressOnPoint: (pointProps) => {
    addOut(`- longPressOn:
    point: ${pointProps.x},${pointProps.y}
`);
  },
  /**
   * Performs a long press on a text element visible on the screen.
   * @param text - The visible text to long press.
   */
  longPressOnText: (text) => {
    addOut(`- longPressOn: ${text}
`);
  },
  /**
   * Swipes left from the screen center.
   */
  swipeLeft,
  /**
   * Swipes right from the screen center.
   */
  swipeRight,
  /**
   * Swipes down from the screen center.
   */
  swipeDown,
  /**
   * Swipes up from the screen center.
   */
  swipeUp,
  /**
   * Swipes from a specified start point to an end point.
   * @param start - Starting coordinates for the swipe.
   * @param end - Ending coordinates for the swipe.
   */
  swipe: (start, end) => {
    addOut(
      `- swipe:
    start: ${start.x}, ${start.y}
    end: ${end.x}, ${end.y}
`
    );
  },
  /**
   * Inputs text into the focused or specified input element.
   * @param text - The text to input.
   * @param id - Optional testId of the input element.
   */
  inputText,
  /**
   * Inputs a random name into the focused or specified input element.
   * @param id - Optional testId of the input element.
   */
  inputRandomName,
  /**
   * Inputs a random number into the focused or specified input element.
   * @param id - Optional testId of the input element.
   */
  inputRandomNumber,
  /**
   * Copies text from an element identified by its testId.
   * @param id - The testId of the element to copy text from.
   */
  copyTextFrom,
  /**
   * Inputs a random email address into the focused or specified input element.
   * @param id - Optional testId of the input element.
   */
  inputRandomEmail,
  /**
   * Inputs random text into the focused or specified input element.
   * @param id - Optional testId of the input element.
   */
  inputRandomText,
  /**
   * Erases a specified number of characters from the focused or specified input element.
   * @param chars - Number of characters to erase.
   * @param id - Optional testId of the input element.
   */
  eraseText,
  /**
   * Opens a specified URL or deep link.
   * @param url - The URL or deep link to open.
   */
  openLink: (url) => {
    addOut(`- openLink: ${url}
`);
  },
  /**
   * Navigates to a specified path using the deep link base.
   * @param path - The path to navigate to.
   */
  navigate: (path) => {
    addOut(`- openLink: ${process.env.deepLinkBase}${path}
`);
  },
  /**
   * Asserts that an element with the given testId is visible.
   * @param id - The testId of the element to check.
   * @param enabled - If true, checks that the element is both visible and enabled.
   */
  assertVisible,
  /**
   * Asserts that an element with the given testId is not visible.
   * @param id - The testId of the element to check.
   */
  assertNotVisible,
  /**
   * Asserts that a specified condition is true.
   * @param condition - The condition to assert.
   */
  assertTrue,
  /**
   * Scrolls down on the screen.
   */
  scroll: () => {
    addOut(`- scroll
`);
  },
  /**
   * Scrolls until an element with the given testId is visible.
   * @param id - The testId of the element to scroll until visible.
   */
  scrollUntilVisible: (id) => {
    addOut(`- scrollUntilVisible:
    element:
      id: "${id}"
`);
  },
  /**
   * Waits until an ongoing animation or video ends.
   * @param maxWait - Optional timeout (in milliseconds) to wait before proceeding.
   */
  waitForAnimationEnd,
  /**
   * Waits until an element with the given testId is visible.
   * @param id - The testId of the element to wait for.
   * @param maxWait - Maximum wait time (in milliseconds) for the element to appear.
   */
  waitUntilVisible,
  /**
   * Waits until an element with the given testId is no longer visible.
   * @param id - The testId of the element to wait for.
   * @param maxWait - Maximum wait time (in milliseconds) for the element to disappear.
   */
  waitUntilNotVisible,
  /**
   * Waits for a specified number of milliseconds.
   * @param ms - The number of milliseconds to wait.
   */
  wait,
  /**
   * Dismisses the software keyboard.
   */
  hideKeyboard: () => {
    addOut(`- hideKeyboard
`);
  },
  /**
   * Takes a screenshot and stores it with the specified filename.
   * @param fileName - The name to save the screenshot as.
   */
  screenshot: (fileName) => {
    addOut(`- takeScreenshot: ${fileName}
`);
  },
  /**
   * Presses the enter key on the software keyboard.
   */
  pressEnter: () => {
    addOut(`- pressKey: Enter
`);
  },
  /**
   * Presses the home button on the device.
   */
  pressHomeButton: () => {
    addOut(`- pressKey: Home
`);
  },
  /**
   * Presses the lock button on the device.
   */
  pressLockButton: () => {
    addOut(`- pressKey: Lock
`);
  },
  /**
   * Presses the back button on Android devices.
   */
  back: () => {
    addOut(`- pressKey: back
`);
  },
  /**
   * Decreases the device volume.
   */
  volumeDown: () => {
    addOut(`- pressKey: volume down
`);
  },
  /**
   * Increases the device volume.
   */
  volumeUp: () => {
    addOut(`- pressKey: volume up
`);
  },
  /**
   * Stops the current app or the specified app by appId.
   * @param appId - Optional appId to specify which app to stop.
   */
  stopApp: ({ appId } = {}) => {
    addOut(appId ? `- stopApp: ${appId}
` : `- stopApp
`);
  },
  /**
   * Repeats a set of actions a specified number of times.
   * @param props - The properties of the repeat command.
   * @param func - The function containing actions to repeat.
   */
  repeat,
  /**
   * Repeats a set of actions while an element is visible.
   * @param matcher - The element matcher to repeat while visible.
   * @param func - The function containing actions to repeat.
   */
  repeatWhileVisible,
  /**
   * Repeats a set of actions while an element is not visible.
   * @param matcher - The element matcher to repeat while not visible.
   * @param func - The function containing actions to repeat.
   */
  repeatWhileNotVisible,
  addMedia
};
const getOutput = (key) => "${output." + key + "}";
export {
  MaestroTranslators as M,
  getOutput
};