20 Sep 2019.

Stb-tester v31 adds support for test-scripts written in Python 3 (Python 2 is still supported, too). To migrate an existing test-pack to Python 3, we recommend the following steps.

Note that there is no immediate pressure to migrate existing Python 2 test-packs. Python 2 test-scripts will continue to work, even after Python 2’s official sunset date in January 2020.

  • Coordinate across your team so that nobody is doing new development with Python 2 until the porting to Python 3 is complete.

  • Check out a new git branch called “python3”.

  • Delete all Python files that you aren’t using, and delete any “dead code” that you aren’t using inside the remaining files. All the test-scripts are version-controlled with git, so there is no need to keep unused code – you can always get it back from the git history if you really need to.

    Commit this deletion to git.

  • Update .stbt.conf to contain the following in the [test_pack] section, and commit the change:

    [test_pack]
    stbt_version = 31
    python_version = 3
    
  • If you install any third-party packages using the config/setup/setup script:

    • Change apt install python-<package-name> to apt install python3-<package-name>.
    • Change pip install <package-name> to pip3 install <package-name>.

    …and commit the changes.

  • Run 2to3 to translate all your Python files to Python 3. This is a script that comes with Python. The name of the script might be 2to3 or 2to3-2.7 depending on your OS. Run it like this:

    2to3 --write tests/*.py
    

    If you have Python files in sub-directories under tests/ you will need to specify them too. You can get the full list of files by running this:

    git ls-files "tests/*.py"
    

    Make sure that you only run each file once through 2to3.

  • Inspect those changes manually, and make sure you understand them. Commit the changes to git.

  • Push your branch, and create a pull request. Stb-tester automatically runs a static analysis of the code in your pull request. This means that you can check that your tests are valid Python 3 code, without even having to run the tests!

    Stb-tester shows the result of the static analysis as a green tick or red cross on your pull request. Click the red cross to see a log with details of the failures.

  • Fix the errors, commit, push, and check the new static analysis results in the pull request. Repeat until the static analysis is green.

    Some of the static analysis checks are about coding style, not actual errors. You can disable these checks if you want, by adding them to .pylintrc in your test-pack (the name of each check is shown in the static analysis log).

  • Finally run the tests to catch any remaining problems that aren’t caught by the static analysis (if any).

  • Merge the pull request to master.

For more details about pull requests, see Development Workflow in the Stb-tester manual.