Configuration

Before running the container, create a local directory that will be mounted at /umai_data inside the container.

Directory Structure

umai_data/
├── pipeline_inputs/
│   ├── api_key.txt        # Your UMAI API key
│   └── test_suite.json    # Tests to run and execution settings
└── outputs/               # Results written here after the run
    └── junit.xml          # Generated when GENERATE_JUNIT_REPORT=true

---

Authentication

This file contains your UMAI API key as a single line.

your-api-key-here

To get an API key:

1. Log in to the UMAI web application
2. Click your profile icon and select Account
3. Go to the API Keys tab
4. Click Create API Key
5. Enter a name, description, and validity period, then click Create

Warning

Never commit your API key to source control. Store it as a secret in your CI/CD system and write it to api_key.txt at runtime.

---

Test Selection

Defines which tests to run and how to execute them. The easiest way to create this file is to export it directly from the UMAI web application:

1. Go to the Library
2. Click the dropdown arrow next to the Run button and select Configure Run
3. In the test selector, choose tests manually or apply a filter query
4. Click Configure Run
5. Select a suite name, environment, and browsers
6. Click Export Config — the file is generated automatically
7. Download the file or copy its contents into pipeline_inputs/test_suite.json

The exported file looks like this:

{
  "filter_query": {
    "status": ["ready"],
    "tags": ["tag-uuid-1", "tag-uuid-2"],
    "folder": ["folder-uuid"]
  },
  "execution_config": {
    "browserOption": "custom",
    "incognito": false,
    "selectedBrowsers": ["chrome"],
    "selectedEnvironment": "your-environment-uuid",
    "testSuiteName": "My CI/CD Test Suite"
  },
  "test_ids": ["test-id-1", "test-id-2"]
}

---

Exit Codes

The container exits with one of the following codes, which your CI/CD system uses to determine build status:

Code	Meaning
0	All tests passed
1	One or more tests failed
2	Infrastructure error (missing config, authentication failure, etc.)

Both GitHub Actions and Jenkins treat a non-zero exit code as a build failure by default, so a failing test will automatically fail the build.

---

Troubleshooting

test_suite.json not found

Ensure the volume mount path is correct and the pipeline_inputs/ directory exists inside the mounted directory.

api_key.txt not found

Ensure the secret was written to pipeline_inputs/api_key.txt before the container runs.

Authentication errors

Verify the API key is valid and has not expired. Generate a new one from Settings > API Keys in the UMAI web application.

Browser issues

The Docker image includes Chrome, Firefox, and Edge. Safari is not supported in the Docker environment.