Getting started

Here is a step by step guide in order to install and try Testplan in your local environment!

Supported Python Versions

Testplan can be used with both Python 2 and 3. Specifically, Testplan is tested to work with Python 2.7 and 3.7, so we recommend choosing one of those.

Warning

The Python 2 interpreter is now very old and will not be maintained by the core team past January 1 2020, so we strongly recommend to use Python 3 where possible. That being said, we have no current plans to drop Python 2 support for users who need it.

Install testplan

Ubuntu/Debian

First install required packages - you will need root privileges.

# For python 2.
sudo apt-get install python python-pip rsync

# For python 3.
sudo apt-get install python3.7 python3-pip rsync
python3.7 -m pip install pip  # Updates to latest pip version.

Native pip install

Install from archive:

# For python 2.
pip install --user https://github.com/Morgan-Stanley/testplan/archive/master.zip
install-testplan-ui

# For python 3.
python3.7 -m pip install --user https://github.com/Morgan-Stanley/testplan/archive/master.zip
install-testplan-ui

Using a virtualenv

Python 2
  1. Install virtualenv.

    pip install virtualenv
    
  2. Create a virtualenv.

    virtualenv testplan-oss
    cd testplan-oss
    source bin/activate
    
  3. Install testplan and its dependencies into the virtual env.

    pip install https://github.com/Morgan-Stanley/testplan/archive/master.zip
    install-testplan-ui
    
Python 3
  1. Create a virtualenv.

    python3.7 -m venv testplan-oss
    cd testplan-oss
    source bin/activate
    
  2. Install testplan and its dependecies into the virtual env.

    pip install https://github.com/Morgan-Stanley/testplan/archive/master.zip
    install-testplan-ui
    

Other Linux Distros

For non-Debian Linux distributions you should be able to install using similar steps as for Ubuntu/Debian - just check the docs for your distro’s package manager (e.g. yum, dnf, pacman) for how to install the required packages instead of using apt-get.

MacOS

Install homebrew.

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Install python:

# Python 2.
brew install python@2

# Python 3.
brew install python

Native pip install

Warning

This will install testplan package with all the dependencies specified in the requirements.txt file. For a quick basic installation, also check the Using a virtualenv guide.

Install from archive.

# For python 2.
sudo pip install https://github.com/Morgan-Stanley/testplan/archive/master.zip
install-testplan-ui

# For python 3.
sudo pip3 install https://github.com/Morgan-Stanley/testplan/archive/master.zip
install-testplan-ui

Using a virtualenv

  1. Install virtualenv.

    # Python 2.
    pip install virtualenv
    
    # Python 3.
    pip3 install virtualenv
    
  2. Create a virtualenv.

    virtualenv testplan-oss
    cd testplan-oss
    source bin/activate
    
  3. Clone testplan repo.

    git clone https://github.com/Morgan-Stanley/testplan.git
    cd testplan
    
  4. Install dependecies and setup.

    pip install .
    install-testplan-ui
    

Windows

Using subsystem

You can follow the ubuntu guide while using a windows subsystem.

Native pip install

For native installation using pip package management system:

  1. Install git.

  2. Install python.

  3. Open the windows command prompt.

  4. Install pip.

    C:\path\to\installed\interpreter\python.exe get-pip.py
    
  5. Install from archive.

    pip install https://github.com/Morgan-Stanley/testplan/archive/master.zip
    

Warning

The install-testplan-ui currently can’t be called on Windows after installing from archive. It will work if installed through virtualenv. You can manually run if Node.js and npm is installed:

C:\path\to\installed\interpreter\python.exe C:\path\to\installed\Scripts\install-testplan-ui

If this isn’t installed the --ui arg will not work properly (the web server will start but the UI won’t load). Read more about the browser output here. Raise a GitHub issue if further assistance is needed.

Using a virtualenv

Installation using a virtualenv:

  1. Install git.

  2. Install python.

  3. Open the windows command prompt.

  4. Install pip.

    C:\path\to\installed\interpreter\python.exe get-pip.py
    
  5. Install virtualenv.

    pip install virtualenv
    
  6. Create a virtualenv.

    virtualenv -p C\:path\to\installed\interpreter\python.exe testplan-oss
    cd testplan-oss
    .\Scripts\activate
    
  7. Clone testplan repo.

    git clone https://github.com/Morgan-Stanley/testplan.git
    cd testplan
    
  8. Install dependecies and setup.

    # Skip heavy dependencies but miss some functionality.
    pip install -r requirements-basic.txt
    python setup.py develop --no-deps
    python install-testplan-ui
    

Via Docker

Installation

To install docker, you can follow the instructions for your OS from this list:

  1. Ubuntu/Debian. For the latest available instructions, please visit the official docker installation instructions for Ubuntu/Debian.

    sudo apt-get update
    sudo apt-get remove docker docker-engine docker.io
    sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
    sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
    sudo apt-get update
    sudo apt-get install docker-ce
    
    sudo usermod -aG docker $USER
    # now LOGOUT and LOGIN again!
    
  2. MacOS. For the latest available instructions, please visit the official docker installation instructions for MacOS.

  3. Windows. For the latest available instructions, please visit the official docker installation instructions for Windows.

Available images

Docker images for testplan are provided for two python versions, python2 and python3.

The images can be retrieved with the following commands:

# Python 2
docker pull chiotis/testplan:2

# Python 3
docker pull chiotis/testplan:3

Interactive docker session

To try testplan in an interactive docker session, you can type:

docker run -it chiotis/testplan:2 bash

The source code is available to explore in /work.

Docker batch execution

To run testplan docker image in batch mode, you’ll need to add your code as a docker volume when running the image. If the test_plan.py file is in $PWD, directory, the docker command will be:

# Example directory that contains test_plan.py file.
cd examples/Assertions/Basic

docker run -v $PWD:/work -it chiotis/testplan:2

If your testplan file has a name other than test_plan.py, you can add it as an argument in the docker run command:

# Example directory that contains test_plan.py file.
cd examples/Assertions/Basic

docker run -v $PWD:/work -it chiotis/testplan:2 ./my_test_plan.py

If you require special arguments for test_plan.py, you can just append them after the docker image:

# default test_plan.py
docker run -v $PWD:/work -it chiotis/testplan:2 --pdf test.pdf

# custom my_test_plan.py
docker run -v $PWD:/work -it chiotis/testplan:2 ./my_test_plan.py --pdf test.pdf

Run testplan

Our examples

There are some ready made examples demonstrating testplan functonality/features and can be found within the repo under examples directory.

On Ubuntu/MacOS/etc:

# See all the examples categories.
cd examples
ls

# Run an example demonstrating testplan assertions.
cd Assertions/Basic
./test_plan.py
# Create a pdf report and open in automatically.
./test_plan.py --pdf report.pdf -b

On Windows:

# See all the examples categories.
cd examples
dir

# Run an example demonstrating testplan assertions.
cd Assertions\Basic
python test_plan.py
# Create a pdf report and open in automatically.
python test_plan.py --pdf report.pdf -b

Also find all our downloadable examples here.

Internal tests

To verify the correct setup process you can execute the internal unit/functional tests. Some tests may be skipped due to optional dependency packages (i.e sklearn used on ‘Data Science’ examples category).

cd tests

# Unit tests.
pytest unit --verbose

# Functional tests.
pytest functional --verbose

Writing custom drivers

Testplan drivers are designed to be able to be inherited/extended and create new ones based on the user specific environment. Here is a section explaining how to create drivers for custom applications and services. You can contribute missing drivers or improvements to the existing ones by following the contribution process.

Installing Testplan for development

If you would like to develop on testplan itself, great! You can follow the relevant instructions above for installing testplan on your platform (Linux, MacOS or Windows) - but instead of installing from the archive, clone the repo with git and make a development install like:

git clone https://github.com/Morgan-Stanley/testplan.git
cd testplan
pip install -r requirements.txt
install-testplan-ui --dev

Alternatively, you can pull and run a portable testplan dev env using docker. See section on docker above for instructions on installing docker itself, then you can simply run:

docker pull ryancollingham/dev_env:testplan
docker run -it ryancollingam/dev_env:testplan

That will drop you into a shell with the testplan dependencies pre-installed, the testplan codebase checked out and installed in a development (i.e. editable) mode, and some other useful development tools installed. This dockerised environment is shell-only so you can use the installed vim editor to edit code (of course emacs developers are also welcome on testplan).