@appium/support

What is @appium/support?

@appium/support is a utility library that provides various helper functions and classes to support Appium's core functionalities. It includes utilities for file system operations, logging, process management, and more.

What are @appium/support's main functionalities?

File System Utilities

This feature provides various file system utilities such as reading, writing, and manipulating files. The code sample demonstrates how to create a file, write to it, and read its content.

const { fs } = require('@appium/support');

async function createFile() {
  const filePath = './example.txt';
  await fs.writeFile(filePath, 'Hello, world!');
  const content = await fs.readFile(filePath, 'utf8');
  console.log(content); // Output: Hello, world!
}

createFile();

Logging

This feature provides a logging utility that allows you to log messages at different levels (info, warn, error). The code sample demonstrates how to create a logger and log messages at different levels.

const { logger } = require('@appium/support');

const log = logger.getLogger('example');
log.info('This is an info message');
log.warn('This is a warning message');
log.error('This is an error message');

Process Management

This feature provides utilities for managing system processes, such as executing shell commands. The code sample demonstrates how to execute a shell command and handle its output.

const { exec } = require('@appium/support');

async function runCommand() {
  const { stdout, stderr } = await exec('echo Hello, world!');
  if (stderr) {
    console.error(`Error: ${stderr}`);
  } else {
    console.log(`Output: ${stdout}`); // Output: Hello, world!
  }
}

runCommand();

Other packages similar to @appium/support

fs-extra

fs-extra is a package that extends the native Node.js file system module with additional methods and promises support. It provides similar file system utilities as @appium/support but focuses solely on file system operations.

winston

winston is a versatile logging library for Node.js that provides a wide range of logging capabilities, including multiple transports, log levels, and formatting options. It offers more advanced logging features compared to the logging utility in @appium/support.

child_process

child_process is a core Node.js module that provides the ability to spawn and manage system processes. It offers similar process management functionalities as the exec utility in @appium/support but is more low-level and requires more boilerplate code.

README

appium-support

Utility functions used to support Appium drivers and plugins.

Usage in drivers and plugins

It is recommended to have Appium as a peer dependency in driver and plugin packages. Add the following line to peerDependencies section of your module's package.json:

  "peerDependencies": {
    "appium": "^<minimum_server_version>"
  }

Afterwards import it in your code similarly to the below example:

import {timing, util} from 'appium/support';

Usage in helper modules

If you want to use this module in a helper library, which is not a driver or a plugin, then add the following line to dependencies section of your module's package.json:

  "dependencies": {
    "@appium/support": "<module_version>"
  }

Afterwards import it in your code similarly to the below example:

import {timing, util} from '@appium/support';

Categories

All utility functions are split into a bunch of different categories. Each category has its own file under the lib folder. All utility functions in these files are documented.

fs

Most of the functions there are just thin wrappers over utility functions available in Promises API.

env

Several helpers needed by the server to cope with internal dependencies and manifests.

console

Wrappers for the command line interface abstraction used by the Appium server.

image-util

Utilities to work with images. Use sharp under the hood.

log-internal

Utilities needed for internal Appium log config assistance.

logging

See below

mjpeg

Helpers needed to implement MJPEG streaming.

net

Helpers needed for network interactions, for example, upload and download of files.

node

Set of Node.js-specific utility functions needed, for example, to ensure objects immutability or to calculate their sizes.

npm

Set of npm-related helpers.

plist

Set of utilities used to read and write data from plist files in javascript.

process

Helpers for interactions with system processes. These APIs don't support Windows.

system

Set of helper functions needed to determine properties of the current operating system.

tempdir

Set of helpers that allow interactions with temporary folders.

timing

Helpers that allow to measure execution time.

util

Miscellaneous utilities.

zip

Helpers that allow to work with archives in .ZIP format.

logger

Basic logger defaulting to npmlog with special consideration for running tests (doesn't output logs when run with _TESTING=1 in the env).

Logging levels

There are a number of levels, exposed as methods on the log object, at which logging can be made. The built-in ones correspond to those of npmlog, and are: silly, verbose, info, http, warn, and error. In addition there is a debug level.

The default threshold level is verbose.

The logged output, by default, will be level prefix message. So

import { logger } from 'appium-support';
let log = logger.getLogger('mymodule');
log.warn('a warning');`

Will produce

warn mymodule a warning

Environment variables

There are two environment variable flags that affect the way logger works.

_TESTING

• _TESTING=1 stops output of logs when set to 1.

_FORCE_LOGS

• This flag, when set to 1, reverses the _TESTING

Usage

log.level

• get and set the threshold level at which to display the logs. Any logs at or above this level will be displayed. The special level silent will prevent anything from being displayed ever. See npmlog#level.

log[level](message)

• logs to level

import { logger } from 'appium-support';
let log = logger.getLogger('mymodule');

log.info('hi!');
// => info mymodule hi!

log.unwrap()

• retrieves the underlying npmlog object, in order to manage how logging is done at a low level (e.g., changing output streams, retrieving an array of messages, adding log levels, etc.).

import { getLogger } from 'appium-base-driver';
let log = getLogger('mymodule');

log.info('hi!');

let npmlogger = log.unwrap();

// any `npmlog` methods
let logs = npmlogger.record;
// logs === [ { id: 0, level: 'info', prefix: 'mymodule', message: 'hi!', messageRaw: [ 'hi!' ] }]

log.errorAndThrow(error)

• logs the error passed in, at error level, and then throws the error. If the error passed in is not an instance of Error (either directly, or a subclass of Error) it will be wrapped in a generic Error object.

import { getLogger } from 'appium-base-driver';
let log = getLogger('mymodule');

// previously there would be two lines
log.error('This is an error');
throw new Error('This is an error');

// now is compacted
log.errorAndThrow('This is an error');