Basic Workflow

Iris can be invoked in several ways, depending on your workflow.

One important note:
Running Iris on your primary machine can be very risky, as it takes over keyboard and mouse input while active. If you develop or deploy Iris, be aware of this and close any active applications.

For all use cases below, follow the instructions in the setup document to enable the virtualenv, i.e.:

pipenv install
pipenv shell
iris <target name> <args>

---

Deploying Iris

• You can use the Control Center to run Iris in a visual manner. This is done by default when invoking iris -k.
• You can use command-line arguments for more low-level control over Iris. This will cause Iris to skip the Control Center and immediately run tests.
• If this is to be done via a script, cron job, or other mechanism, you will need to adjust the command line arguments to prevent the Control Center from launching. One simple way to do this is to specify the desired build you wish to test, e.g. iris -f beta.
• If you are invoking Iris in a cron job, special consideration will be needed so that the shell commands are properly executed in your script. In this case, replace use of pipenv shell with pipenv run iris <args>.

---

Developing your own target and tests for Iris

Iris is also available as a PyPI library for import into your project, named moziris. You can write your own custom target and tests, and Iris will run them. An Iris "target" is the application you wish to test, and it is a pytest plugin that inherits from moziris.base.target. See targets/sample for a minimal example of how to write one, or see the iris-firefox project for an example of Iris used to test the Firefox web browser.

To use moziris in your own project as an external library:

• Set up a python project (version 3.7.3 or above) that imports the moziris library via a Pipfile.
• Create a folder in the root of your repo named targets and create a folder inside that named after your target, e.g. targets/foo.
• Create your target logic via a main.py file, inheriting from moziris.base.target. Use the examples mentioned above for reference. This file defines a pytest plugin, which is documented in depth on their web site.
• Create a folder in the root of your repo named tests and create a folder inside that with the same name as your target, e.g. tests/foo.
• Put your tests in this folder. The test format, by default, is what pytest specifies, but you can customize it using a pytest.ini file inside this test folder. Again, consult the examples used in the projects mentioned here.
• Configure your system for Iris using the bootstrap script in the root of this repo.
• Follow the instructions in the Setup page to run your project, using your target name in the command line arguments:

iris foo <args>

---

Iris and virtualized environments

• Iris may be used in a desktop virtual machine, such as VMware or VirtualBox. However, due to various issues with screen resolution, video drivers, key handling, and font sizes, the behavior can be unpredictable. It is not recommended for this reason. However, we are exploring solutions, and when we establish a standard configuration, we will provide details.
• We are working on a Docker image to simplify deployment for our developers. Please check back for progress.

---

Dealing with test failures

From time to time you may see test failures, as is expected. Some of these failures might be false. You can follow this workflow when dealing with test failures.

1. Make note of the tests that failed on the first run through (saving the log is recommended)
2. Trigger another test run with just the tests that failed (-a flag from the command line)
3. Adjust the -m flag with each run, which specifies how many times to run a failing test before giving up. The default is 3, but can be decreased or increased to adjust tolerance for failure.