[Iris 2.0] New Project Structure

Title:

New Project Structure

Author(s):

Matt Wobensmith

Tracking issue:

TBD

Short description:

Since we are porting to Python 3 and making use of pytest, we have the opportunity to better structure our project for cleaner code and to enable extensibility.

Use case(s):

Iris developers will have a better understanding of what code belongs to the core API and what is meant for Iris itself. Also, this structure will make it easier for third parties to add target modules to Iris.

Implementation:

• Overview

This feature will enable the following work items:

• Port to Python 3
• Integrate pytest
• Separate test case API from internal Iris core code
• Enable extensibility
• Test case base class

Before we can finalize those, we need to establish a basic project structure.

• Sample code

This is a proposed directory structure for the project.

/iris2 [0]
    /bootstrap [1]
    config.ini [2]
    setup.py
    /src [3]
        __main__.py [4]
        /base [5]
            __init__.py
            target.py
            test.py
        /configuration [6]
        /control_center
        /core
            __init__.py
            /api [7]
            /util [8]
        /targets [9]
            /firefox
                app.py [10]
                /bootstrap [11]
        /test_rail [12]
    /tests
        /firefox
            pytest.ini [13]
            /a
                /b
                    some_test.py [14]
    /tools

• [0] The root directory iris2 will eventually change its name back to iris when the project is complete.
• [1] Bootstrap scripts that pertain to the whole project go here.
• [2] Any config files go here, outside of core Iris source code.
• [3] The src directory is intended to separate Iris core - logic and namespace - from tests, as advised here.
• [4] The __main__.py contains Iris core logic.
• [5] This directory contains base classes for test cases and targets. These base classes only contain data that pertains to Iris as a whole and do not have target-specific data.
• [6] Can we move the configuration folder here?
• [7] The api directory contains the API that is exposed to test cases. No internal Iris APIs go in here.
• [8] The utils directory is intended for internal Iris APIs, and can reference the external api sibling directory that test cases use.
• [9] The targets directory (formerly known as "applications" or modules) is the extensible part of Iris where each app defines its logic.
• [10] The app.py is the target's main logic. Every target module must have one, and this file contains a class that inherits from a base class in src/iris/base/target.py.
• [11] Each target module can add its own bootstrap scripts that will be dynamically run by the master bootstrap scripts in [1].
• [12] Can we move the test_rail directory here?
• [13] Each target's test folder can deploy a pytest.ini file in order to customize pytest features, such as test and function naming conventions.
• [14] For Firefox, we would like our tests to be named whatever we want (and not the default "test_" pytest prefix). Also, we need the ability to have nested folders and packages.

• New and/or changed files and directories

Too many to list - see above.

• Control Center

This should not impact the Control Center.

• Localization

This should not impact localization.

• Documentation

This should not impact documentation.

• Bootstrap

No impact on bootstrap script, although we would add a per-target bootstrap folder that will be described in our extensibility feature.

• Setup

No impact on setup.

Risks:

• Dependencies on other people/teams/software.

We must finalize this before we do any major work. Making changes to this later is painful.

Open question:

• Where does the current Firefox helpers directory go? Now that we are separating Firefox from core code, it should be target-specific. We can move it to targets/firefox/helpers but we also need to make sure it's available to tests in our test directory. We will have to solve this when we implement the Iris test case base class, which then might be followed by an intermediate Firefox test case class that only our module uses. TBD with that work.

• Other factors that could influence functionality or schedule.

None known.

Estimated schedule:

• xxxx-xx-xx Spec due date (this)
• xxxx-xx-xx Implementation
• xxxx-xx-xx Code review
• xxxx-xx-xx Testing
• xxxx-xx-xx Final check-in date