> For the complete documentation index, see [llms.txt](https://docs.mozark.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozark.ai/no-code-studio/authoring-tests/importing-an-existing-script.md).

# Importing an existing script

Already have an Optics test suite? Import it and carry on editing it in App Studio, with the device screenshot, modules, versions and data sets.

Go to **Test Cases** and click **Import script**.

## What you can upload

The **CSV files** of the suite. App Studio works out what each file is from its **header row**, never from its name, so folder structure and file names do not matter.

| Header contains                                            | The file is read as    | Becomes                                                             |
| ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------- |
| `test_case`, `test_step`                                   | Test cases             | A test case per name                                                |
| `module_name`, `module_step` (+ `param_1`, `param_2`, ...) | Modules                | A module at version 1.0                                             |
| `element_name`, `element_id` (+ fallback id columns)       | Elements and variables | Elements, or variables when the value is data rather than a locator |
| `error_code`, `match_string`                               | Error definitions      | Stored as project error codes. See Error definitions                |
| Anything else with a header and at least one row           | A data file            | A data set                                                          |

Two file types are **rejected, not skipped**:

* **`.zip` archives.** The contents cannot be read, so the suite cannot be checked. Unzip and upload the CSV files.
* **`.yaml` / `.yml` suite files**, other than `config.yaml`. YAML import is not supported yet, and a suite that hides entities in one cannot be validated.

`config.yaml` is ignored quietly. It carries nothing that is imported.

{% hint style="warning" %}
Header spelling matters to Optics itself: it looks for `test_case`, not `Test Case`. Case does not matter; spaces instead of underscores do. A file Optics ignores may still import here, so if a suite imports but never ran properly upstream, check the headers first.
{% endhint %}

## The wizard

```
Upload  ──►  Validate  ──►  Review  ──►  Done
```

1. **Upload.** Drop the files in, or use **Select files** / **Select folder**. Picks accumulate, so you can add `elements.csv` after `modules.csv`. Files that are not CSV, YAML or zip are filtered out of the selection.
2. **Validate.** The suite is checked with Optics' own linter. Every finding is anchored to a **file and a line**. Nothing is written at this stage.
3. **Review.** When there are no errors you get counts of what will be created: test cases, modules, actions, elements, variables and data sets, plus any warnings about how things were mapped.
4. **Import.** The suite is re-validated server side and written in a **single transaction**. Either all of it lands or none of it does. There is no half-imported state to clean up.

## What your suite becomes

| Your suite                             | Becomes                                                                             |
| -------------------------------------- | ----------------------------------------------------------------------------------- |
| A test case                            | A test case in **Test Cases**, built from module blocks in order                    |
| A module                               | A versioned module at version 1.0 in **Modules**                                    |
| An element                             | An entry in **Elements**, with its fallback ids, inlined onto the steps that use it |
| A `${variable}` with a literal value   | A static variable                                                                   |
| A `${variable}` set to `ENV:SOMETHING` | An env variable                                                                     |
| A `read_data` lookup                   | A lookup variable bound to the right data set and key column                        |
| A data CSV                             | A data set, with its key column detected from the lookup that reads it              |

The `read_data` loaders and the device-serial capture step are recognised and turned back into data sets and lookup variables, so they do not clutter your step list. They are regenerated automatically when you run.

### Names already in the project

Elements, variables and data sets are **reused** when the name matches (ignoring case), so re-importing an updated suite merges into the project library instead of littering it with copies.

Modules and test cases are **never** merged into: a clash gets a suffix, so you end up with `Login (imported)`, `Login (imported 2)` and so on. The Review and Done screens list what was reused.

## Fixing a broken script

Errors block the import. Warnings do not, but each one is telling you something about how your suite will behave. Fix the file at source and upload again.

### Errors

| Message                                                           | What happened                                                                       | Fix                                                                                                                         |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Module 'X' not found`                                            | A test step names a module no uploaded file defines                                 | Upload the missing modules file, or correct the spelling. Module names must match exactly                                   |
| `'X' is not a keyword or module`                                  | A module step names neither an Optics keyword nor another module                    | Correct the keyword spelling, or add the module the step is calling                                                         |
| `'X' takes 1-2 params, got 3`                                     | The step passes the wrong number of parameters                                      | Usually a stray comma, or a notes column that is not named `description`. Remove the extra cell, or rename the column       |
| `'x' is not a defined element or variable`                        | A `${x}` reference has no matching row in an elements file, and no step produces it | Add the row, or fix the name. Data set column headers do not count: a column named `username` does not define `${username}` |
| `Row has fewer than 2 columns, which aborts the whole run`        | A short row in a test cases or error definitions file                               | Fill in the missing cell or delete the row. Optics crashes on these before anything runs                                    |
| `Cannot read inside an archive` / `Cannot read a YAML suite file` | A zip or a non-config YAML was uploaded                                             | Upload the CSV files directly                                                                                               |

### Warnings

| Message                                                     | What it means                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Row has fewer than 2 columns, so it is skipped`            | A short row in a modules or elements file. Optics drops the row, so the step or element silently does not exist |
| `Row has more columns than the header`                      | A ragged row. The extra cells are discarded. Often a comma inside an unquoted cell                              |
| `Whitespace-only line`                                      | A line of spaces. Harmless, but usually a sign of a hand-edited file                                            |
| `Duplicate module / test case 'X', see ...`                 | Two definitions of the same name. The later one wins wherever the files sit, so the first is dead weight        |
| `Duplicate error code / match string`                       | The same code is defined twice, or two rows match the same text and both fire                                   |
| `Row has no error_code / match_string, so it never matches` | An incomplete error definition row                                                                              |

### Things that are no longer errors

If you have imported this suite before and remember them failing:

* The same element name repeated with different ids is how fallback locators are written. Optics gathers them into one list and tries each in turn.
* A ragged row in an elements file loads fine. It is a warning now.

## If something goes wrong

| Message                                       | What to do                                                                                                                       |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| No suite files were uploaded                  | The selection was empty, or held no CSV. Select the CSV files themselves                                                         |
| Suite validation is unavailable               | The validator could not be reached. Nothing was checked and nothing was saved. Retry, and tell your administrator if it persists |
| Suite failed validation; nothing was imported | The files changed between Validate and Import. Validate again                                                                    |
| No test cases found in the uploaded suite     | No file was read as test cases. Check the `test_case` / `test_step` header                                                       |
| Upload the suite CSV files directly to import | A zip was still in the selection. Remove it                                                                                      |
| Import failed                                 | The write was rolled back. Nothing was saved. Retry                                                                              |

### Validation passed, but the counts look wrong

Nothing was rejected, but the Review step shows fewer test cases, modules or elements than the suite has. The usual causes:

* A file was left out of the selection. Add it and validate again.
* A header is misspelled, so the file was read as a data set instead of as test cases or modules. Check the header row against the table above.
* Rows were skipped for being short. Those appear as warnings with their line numbers.

If **0 test cases** are found, the import is refused outright with *No test cases found in the uploaded suite*.

## Worth checking after an import

* **Data set keys.** When no `read_data` lookup reads a data file, the key is guessed as the first column and you get a warning saying so. Open the data set and correct it if the guess is wrong.
* **Recovered descriptions.** If a modules file omits the empty-parameter comma before its description column, the description text lands in a parameter. App Studio detects the case and recovers it, with a warning naming the file. Verify those steps in the editor.
* **Imported locators land under Android.** An iOS suite imports, but its locators sit in the Android slot in the Elements library.

## After importing

Your suite is now editable like anything else in App Studio:

* Open a test case and record new steps against a live device.
* Open an imported module and edit it on a device, then save a new version.
* Open a data set and edit the grid, or add columns.
* [Run it](https://docs.mozark.ai/no-code-studio/running-and-reporting/running-tests).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mozark.ai/no-code-studio/authoring-tests/importing-an-existing-script.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.