utam

UTAM - UI Test Automation Model

UI Test Automation Model (UTAM) is based on the popular Page Object model design pattern commonly used in UI tests. Instead of using an object-oriented class to write a page object, a UTAM page object is authored in JSON, and described by an easy-to-understand UTAM grammar. The utam package is the entry point for generating JavaScript page objects.

Installation

Add utam as a devDependency in your package.json:

yarn add --dev utam
# or via npm
npm add --dev utam

Usage

This package exposes a CLI tool, utam, that

• generates JavaScript page objects from declarative JSON files
• generates UTAM JSON files from HTML

It's the main package that should be installed to use UTAM for page object authoring and generation.

Visit wdio-utam-service to learn how to use UTAM with WebDriverIO in your UI tests.

Configure and run the UTAM Compiler

Start by configuring the UTAM compiler to match your project structure and requirements.

Generate JavaScript page objects by running utam either via the cli:

npx utam -c utam.config.json

Or via a script in your package manifest:

// package.json
{
    // ...
    "scripts": {
        "build": "utam -c utam.config.json"
    }
    // ...
}

Invoke the script with:

yarn build

# or via npm
npm run build

Configure and run the UTAM Generator

Start by configuring the UTAM generator to match your requirements.

Generate UTAM JSON page objects by running utam-generate either via the cli:

npx utam-generate -c generator.config.json

Or via a script in your package manifest:

// package.json
{
    // ...
    "scripts": {
        "build": "utam-generate -c generator.config.js"
    }
    // ...
}

CLI

Use the utam command to run the UTAM compiler from the command line:

utam [options]

Note: You don't have to specify options.

--config

Use the --config option to specify the compiler configuration file path:

utam --config path/to/project/utam.config.json

Note: you don't need to specify that option if your project has a utam.config.js config file at the package root or if your package.json file has a utam configuration key.

--projects

Use the --projects option to specify projects to use in compilation:

# Project1 contains either a utam.config.js or has a `utam` key in `package.json`
utam --projects path/to/project1 path/to/project2/utam.config.json

A project is a folder that contains some configuration for the UTAM compiler. A valid project is a folder that contains either:

1. A utam.config.js config file
2. A utam.config.json config file
3. A utam config object in the package manifest (package.json)

Note: A configuration file can have any name. The utam.config prefix is a convention.

--target

Use the --target option to specify the module system of default page objects. Options are (commonjs or module).

# Generate page objects that use ES Modules by default
utam --target module

# Generate page objects that use CommonJS by default
utam --target commonjs

Default page objects are the generated page objects with a .js file extension.

Generate UTAM Config via API

1. Generate config with all values set to default, returns normalized config.

generateDefaultCompilerConfig(override: Partial<UtamProjectConfig>): NormalizedUtamProjectConfig

• override is optional partial UTAM config if default values needs to be overridden

2. Generate default config using previous method and write it to a file, returns absolute path to generated compiler config.

writeCompilerConfig(configOptions: ConfigFileOptions = {}, override: Partial<UtamProjectConfig> = {}): string

• configOptions optional parameters related to config

  • rootDir root directory of the project with UTAM page objects, default is process.cwd()
  • configType type of the config: json or js, default is json
  • configName name of the file to write config to, default is utam.config.json or utam.config.js depending on config type

• override is optional partial UTAM config if default values needs to be overridden

Generate UTAM Config from command line

Generate UTAM default config by running utam-config via the cli:

npx utam-config

By default it will create utam.config.json in current folder. Use the --config option to specify the compiler configuration file path:

utam-config --config path/to/project/utam.config.json
utam-config -c path/to/project/utam.config.js

If file name ends with js, generated config will be in JavaScript format.

Documentation

utam.dev has all the information you need to get started with UTAM, including guides, tutorials and the JSON grammar.