> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/launch-testview-and-run-a-test.md).

# Launch TestView & Run a Test

To demonstrate how to launch TestView and run a test, this guide uses the **HVAC\_500kV\_6Bus** example found under **Transmission**.

1. Launch HYPERSIM.
2. Go to **File → Options**, select the **HVAC\_500kV\_6BUS.ecf** example, and click **Open Example**.
3. When prompted, choose a folder where a **copy** of the example model will be saved.
4. With the model open, go to the **HYPERSIM** tab and click **Load** sensors file

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-f5b166bf43d8773a973c189d85e62ab1c147dce5%2Fimage%20(1235).png?alt=media" alt=""><figcaption></figcaption></figure>

5. A file browser opens at the model directory. Select the `.csv` sensors file to load the sensors.
6. Start and then stop it immediately. This step ensures that, once in TestView, using **Load Preferences from HYPERSIM** in the **HYPERSIM Settings** command will correctly import all preferences. **Do not skip this step.**

You can now proceed with the TestView workflow.

{% stepper %}
{% step %}
**Launch TestView**

TestView can be launched directly from HYPERSIM via the **TestView** button.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8a5f9623194fa9e74ce2e2e51349b6276e5b7d4b%2Fimage%20(1208).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Create a new TestView project**

In TestView, go to **File → New Project…**, enter a project name, and click **Apply**. It is recommended to use the default directory.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-173ced36b482c272dab092f9f8e0ac3032640cae%2Fimage%20(1236).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Create a new study**

Right‑click the project icon in the left panel and choose **New Study…**. A project may contain several studies, each with their own tests.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-3c9945e70b330be939652b377cd5ec3d164d76d3%2Fimage%20(1237).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Create a new test**

Right‑click the study in the Project tree and choose **New Test…**. Type a test name and press **Apply**. A description is optional, but grouping tests inside a study is recommended.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7d3c408d195908ce024968e94c3d4532854eab59%2Fimage%20(1238).png?alt=media" alt="" width="434"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Add the HYPERSIM Test command**

The first step that must be added to **any** TestView script is the **HYPERSIM Test** command. In the **Palette** tab, click [**HYPERSIM Test**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/test-commands-reference/hypersim/hypersim-test.md) to add it to the script, then click **Apply** in the dialog that appears to insert the command.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-b71352293b1157320a71fae420c6923cbecfc47e%2Fimage%20(1239).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Add the HYPERSIM Settings command**

The second **mandatory** step in **any** TestView script is the **HYPERSIM Settings** command. To add it, first **select the HYPERSIM Test** step in the script, the click **HYPERSIM Settings** in the **Palette** tab to insert it. Commands are always inserted **directly below** the currently selected step in the script.

In the window that appears, first click **IMPORT HYPERSIM (network and sensors)**, then click **Load Preferences from HYPERSIM**. If the model was previously run (as instructed earlier), all preferences should load correctly. Click **Apply** to close the window and add the command to the test sequence.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-e35d1762e3aa1d1bf1081f727564c4c9664e6bb3%2Fimage%20(1240).png?alt=media" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Add more commands (optional)**

More commands can now be added to the test sequence. For details on all available commands, refer to the [**Test Commands Reference**](https://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/test-commands-reference.md) section.
{% endstep %}

{% step %}
**Run the test**

In the **Runner** tab, ensure the **Current test only** option is selected. Then click **Play** (the arrow icon) to execute the test.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-38ba6fdd971d336ef04a1beafaa3405a55758fed%2Fimage%20(1241).png?alt=media" alt=""><figcaption></figcaption></figure>

During execution, observe the **Stdout** console. It should display output similar to the example below, confirming that the test started and completed successfully.

To re‑run the test, press **Play** again. A prompt will appear asking whether to **unlock** the test.\
TestView uses a lock/unlock mechanism to preserve data integrity:

* When a test finishes, its results are **locked** to prevent accidental overwrites.
* A test must be **unlocked** before it can be executed again (unless the *Auto‑unlock* option is enabled in the Runner tab).

This basic test simply starts the simulation and stops it. It serves as the required starting point for any TestView sequence. Full examples build on this minimal setup.

{% hint style="info" %}
**Important Notes About the Model Copy**

TestView does **not** interact with the original HYPERSIM model.\
When the test is run for the first time, TestView creates a **copy** of the model in `[ProjectName] \ bank \ hnk \ [ProjectName].ecf`. All subsequent test operations use this copy. If you completely close HYPERSIM, it is recommended to:

1. Re‑open the **copied** model,
2. Run it once,
3. Then re‑open TestView.

Any modifications made to the **original** model will **not** be reflected in TestView unless you delete the copied version, prompting TestView to create a new one. You may instead edit the **copy** directly within the project folder. This behavior guarantees **test reproducibility** and prevents accidental overwriting or inconsistency between model versions.
{% endhint %}
{% endstep %}
{% endstepper %}


---

# 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://www.opal-rt.com/docs/hypersim/automation-api-and-scripting/automate-using-testview/launch-testview-and-run-a-test.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.
