AutoKey run tox tests

autokey_run_tox_tests.md

AutoKey run tox tests

We don't have a tox.ini file and it may be necessary. From what I've been able to find out online:

• The setup.cfg and setup.py files are for building distributions.
• The tox.ini file is for running tests in virtual environments that are created on-the-fly.

In reference to the official AutoKey documentation at https://autokey.github.io/autokey/ Silico_Biomancer (AKA BlueDrink9) said: Iirc on the branch with the docs changes, if you run something like tox -e docs it should re-generate the files. Should be documented, but probably only on that branch's readme or CONTRIBUTORS.rst atm

Run tox using the version of Python in PATH:

tox -e py

Prepare your computer or virtual machine for development

1. (Optional) Boot into the virtual machine.
2. Grab all available operating-system updates.
3. Update the apt database: sudo apt update
4. Install pip3: sudo apt install python3-pip
5. Install tkinter: sudo apt install python3-tk
6. Install tox: sudo apt install tox
7. Create a GitHub personal access token.
8. Configure your git username by replacing John with your username: git config --global user.name "John"
9. Configure your git user email by replacing John Doe's email address with yours: git config --global user.email "[email protected]"
10. (Optional) Configure your editor as nano instead of the default of vim: git config --global core.editor "nano"
11. (Optional) Configure your pushes to tracking so that they'll go wherever they're being tracked to go automatically based on your clone command: git config push.default tracking

Run the tests

GitHub Actions can be run locally inside of your virtual machine:

1. Open the virtual machine.
2. Open the clone's directory in a terminal window.
3. Choose a testing command to run:
   • Run all tests for all platforms in all environments: tox
   • Run all tests for all platforms in the environment that tox is installed in: tox -e test
   • Run all tests for all platforms in all environments, recreating the virtual environments first: tox -r
   • Run all tests for all platforms in all environments, recreating the virtual environments first: tox --recreate
   • Run all tests for the specified platform in the specified environment: tox -e py37-test
   • Run all tests for the specified platforms in the specified environments: tox -e 'py3{7,11}'-test
   • Run all tests for all platforms iusing the version of Python in PATH: tox -e py
   • Run all tests for the specified platform in all environments: tox -e py37
   • Run individual tests on specified files that start with test_:
     • Run an individual test on the specified file: tox -- tests/test_common.py
     • Run an individual test on the specified file: tox -- tests/test_configmanager.py
     • Run an individual test on the specified file: tox -- tests/test_iomediator.py
     • Run an individual test on the specified file: tox -- tests/test_macro.py
     • Run an individual test on the specified file: tox -- tests/test_phrase.py
     • Run an individual test on the specified file: tox -- tests/test_phrase_runner.py
   • Run a lint test: tox -e lint
   • Run the clean, coverage, and report tests: tox -e clean,coverage,report

Interpret the test results

When interpreting the test results, note that tests can be marked by the developers with skip or xfail if they're expected to fail for some reason, as they might with a feature not implemented yet or a bug not fixed yet.

• Marking a test with skip will prevent that test from being run at all.
• Marking a test with xfail will run that test so you can check if it fails or not.

Interpret the tox output

• SKIPPED means that a test marked with skip wasn't tested, as expected.
• XFAIL means that a test marked with xfail failed, as expected.
• XPASS means that a test marked with xfail passed.

Exit codes for tox tests

https://docs.pytest.org/en/stable/reference/reference.html#exitcode