Developer Guide Unit Tests (WIP)

All changes should be submitted via a pull request against master from a fork. This guide gives details on how to run the unit tests locally using the Makefile or tox, and how to build and release the software.

All notable changes to awscli-login should be documented in CHANGELOG.rst. The format is based on Keep a Changelog, but in reStructuredText format. This project adheres to Semantic Versioning.

Dependencies

Developing and testing the package requires a number of system and Python dependencies as documented below.

System dependencies

POSIX

To run tests on multiple versions of Python you need to install pyenv.

Windows

C++ Build Tools

• Microsoft C++ Build Tools is required.
  • Run pip install --upgrade setuptools
  • Download and install the build tools here.
  • After the installation Visual Studio Installer should open and present some options.
  • Select C++ build tools and ensure the latest versions of MSVCv142 - VS 2019 C++ x64/x86 build tools and Windows 10 SDK are checked.
  • Click install
  • Reboot after install is complete.
• Note: Details on installing and configuring C++ tools on Windows can be found here.

Chocolatey packages

The chocolatey package manager is required for installing prerequisite packages.

• Installing Chocolatey

• Install pyenv-win

  choco install pyenv-win
  

• Install GnuWin32 CoreUtils for Windows (requires admin privileges)

   choco install gnuwin32-coreutils.install
  

• You may need to add C:\Program Files (x86)\GnuWin32\bin to your user path

• Restart your shell to pick up new PATH additions

• Run pyenv update to make sure your list of installers is up-to-date

• Add C:\Users{your_windows_user}\bin to your user path. This path will be used by the make win-tox command to run tests with tox.

Python Dependencies

For development and testing it is recommended to use a virtual environment:

$ pip install virtualenv
$ virtualenv venv

POSIX

On Unix like systems activate the virtual environment then install the Python dependencies using the Makefile:

$ source venv/bin/activate
(venv) $ make deps-posix

Windows

TODO: Add documentation how to activate venv on Windows

Building and testing the package

After all the dependencies are installed running make will build a wheel and tarball in dist, lint and statically analyze the code, and test it using tox and the default system Python. After successfully testing, a coverage report is shown, then documentation is built and tested. To skip building and testing the documentation type make test.

The Makefile is designed to minimize work done, and will not rerun the build or tests unless the source code is changed. To force a new build and testing type make clean.

To run the code that is installed in the tox virtual environment (.tox/wheel) run make shell after building, then configure the plugin for use:

(venv) $ make test
(venv) $ make shell
(wheel) $ aws configure set plugins.login awscli_login
(wheel) $ aws login configure
ECP Endpoint URL [None]: https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Username [None]: your_username
Enable Keyring [False]: 
Duo Factor [None]:     
Role ARN [None]:
(wheel) $ aws login
Password: ********
Factor: passcode
Code: 123456789
(wheel) $ aws logout
(wheel) $ exit
(venv) $

To see the dependencies installed inside the tox virtual environment type make freeze.

Development mode

The disadvantage of the primary Makefile target as shown above is that it requires a wheel. Each time the source code changes a new wheel must be built and installed in the tox virtual environment. To enable rapid development a develop target has been added to the Makefile that directly installs the package in development mode. After the package is installed linting and static analysis are performed, the unit tests are run, and a coverage report is displayed just like the test target. The documentation and doctests are not run by the development target. To build the documentation and run the doctests simply type make docs.

(venv) $ make clean
(venv) $ make develop
(venv) $ aws configure set plugins.login awscli_login
(venv) $ aws login configure
ECP Endpoint URL [None]: https://shibboleth.illinois.edu/idp/profile/SAML2/SOAP/ECP
Username [None]: your_username
Enable Keyring [False]: 
Duo Factor [None]:     
Role ARN [None]:
(venv) $ aws login
Password: ********
Factor: passcode
Code: 123456789
(venv) $ aws logout
(venv) $ exit
$

Running tests against all supported versions of Python

Tox with pyenv can be used to the unit tests against multiple versions of Python.

POSIX

• Run make to build and test the project with the default system Python
• Run make pyenv to install multiple python versions as needed
• Run make tox to run tests with tox against all supported versions of Python

Windows

• Run make to build and test the project with the default system Python
• Run make pyenv-win to install multiple python versions as needed
• Run make tox to run tests with tox against all supported versions of Python

Local Releases

Generally releases are automatically handled by GitHub Actions. Test releases are created whenever a commit to master is pushed. Production releases are created whenever a tag is pushed. This is the preferred method of deployment, but sometimes it may be necessary to create a release locally and push it to PyPI.

PyPI Release

TODO

Test PyPI Release

TODO