Documentation › Troubleshooting & FAQ
Troubleshooting & FAQ
Understanding run states & results
A run has a state (is it finished?) and a result (did it pass?). The states you'll see in the Runs list:
| State | Meaning |
|---|---|
| Active (spinner) | Running now. |
| Success | Passed. |
| Failed | An assertion failed — the test ran but a check didn't hold. |
| Broken | A non-assertion error (e.g. an element wasn't found, a script error). |
| Stopped | Manually stopped. |
| Queued | Waiting for a free execution node (free plans have no parallelism). |
| Waiting | Waiting on a dependency to start. |
| Failed to start | The run couldn't be launched at all — rare; contact support if it persists. |
Failed vs Broken: "Failed" means your test found a problem (an assertion) — often a real defect. "Broken" means the test itself hit an error (a bad locator, a timing issue, an environment problem) — usually a test to fix, not a product bug.
Run problems
| Symptom | Likely cause & fix |
|---|---|
| Run stuck in Queued | No free node. On a free plan runs are serial — wait, or upgrade for a private pool. Check the Runs x/y counter in the status bar. |
| Run is Broken with "element not found" | The locator is stale or you're in the wrong frame. Re-record the step, use a more stable locator, or add a waitForElementPresent. For Maximo, confirm you're inside #manage-shell_Iframe — see the Maximo playbook. |
| Run hits the time limit | mx.run.time_to_live caps run duration (default 300s). Increase it (up to the plan limit) or split the test. |
| No live video | Live video appears a few seconds in and only for single-case runs. Video recording is separate and needs enable_video_recording=true. |
| MXML case won't compile | Check for an unsupported <ui:className> locator (replace with id/css/xpath). View the compile log via Workspace ▸ More options ▸ Compile logs. |
AI test cases
| Symptom | Likely cause & fix |
|---|---|
| Run failed: "did not report a result" | The agent never reached a conclusion. End your script with an explicit "Report what was checked" step, and make sure earlier steps aren't ambiguous or looping. |
| Failed with "loop detected" | The agent got stuck repeating an action. Make the step clearer/more specific, or adjust mx.playwright.aggressiveness_level. |
| The AI did the wrong thing | Open the run's Console output to see each step the agent took, then tighten the wording of the offending instruction (name the exact button/field). |
| No MXML case was produced | Recording needs both mx.record_maximo=true and the recorder credentials (mx.recorder.project_name + mx.recorder.maxtaf_api_key). Missing either → the run executes but records nothing. |
| AI Assistant / AI case errors about the provider | Check Project Settings ▸ AI Configuration — the provider key/model must be set for the provider you're using. |
Recorder & upload
| Symptom | Likely cause & fix |
|---|---|
| Case exports but doesn't appear in MaxTAF | Cloud upload requires PROJECT_NAME, BASE_URL and MAXTAF_API_KEY set, and SAVE_TO_FILE_ONLY=false. Check the recorder's Configuration and validate the API key. |
| Upload rejected (auth error) | The API key or project id is wrong, or the key was invalidated. Regenerate it in Admin ▸ User Settings and re-enter it in the recorder. |
| Case name rejected | Names must contain only letters, numbers, spaces and underscores. Remove other characters. |
| Clicks recorded with a CSS selector instead of an id | The element had no usable id at capture time. Add an assert/store on the field via right-click to capture the id, or edit the locator in the generated MXML. |
| Nothing records inside Maximo | The extension must be allowed to run in all frames. Reload the Maximo tab after enabling the extension so the content script injects into the iframes. |
Parameters
| Symptom | Likely cause & fix |
|---|---|
| A parameter value isn't taking effect | Layers combine by mx.params.source / mx.params.method. A case-level value overrides a project-level one; an empty case-level value can blank a project value. Check the case's parameter config. |
Can't create an mx.* parameter | mx.* names are reserved/standard — set their values, but use custom names for your own variables. |
| Wrong environment being tested | Confirm mx.maximo.address (and any environment URL params) point where you expect; override per run with runParams from CI. |
General FAQ
What's the difference between the AI Assistant and an AI test case?
The AI Assistant is a chat helper that writes/debugs code for you. An AI test case is a runnable test the agent executes. See Writing AI Test Cases.
Which case type should I use?
For Maximo, MXML (usually via the recorder or an AI recording run) is the fast, token-free choice for regression. Use an AI case to author quickly or explore. Java/Python/JavaScript are there when you need full programmatic control.
Where are the AI execution logs?
In the run's Console output section — not the "Log" section.
How do I back up my work?
Use project Export (Settings ▸ Main) for cases/suites/schedules/files/params. Runs aren't included — download the runs folder separately. See Backup & maintenance.
Can I run tests from CI?
Yes — see CI/CD Integration.
How do I get more help?
Use Learn ▸ Support in-app, or the in-app AI Assistant for authoring questions.