Test Environment Setup
This guide it out-of-date. For current recommendations for setting up a development environment, please see the relevant section of the Contributing Guide. As explained there, it is expected that most of the tests can be run on the Ci server and do not need to be run locally. However, in the event that you still need to run tests locally, the general guidelines below may be helpful.
Python-Markdown uses nose and tox for tests. Tox allows the nose tests to easily be run in all supported versions of Python. For that to work, all supported versions of Python need to be installed on the system. Then the testing tools need to be installed.
These instructions assume a typical Ubuntu Linux system (also known to work on Mint).
The simplest way to install multiple Python versions is from the the Deadsnakes PPA. From the command line run the following commands:
$ sudo add-apt-repository ppa:deadsnakes
$ sudo apt-get update
$ sudo apt-get install python3.1 python3.2 python3.3
Adjust that last line to only list the supported versions of Python which are not already installed on the system.
Now, typing pythonX.X on the command line will run Python version X.X:
$ python3.1 --version
Python 3.1.5
$ python3.2 --version
Python 3.2.6
Yes, it is that easy. Skip down to the "Installing the Testing Tools" section to continue.
If you don't want to or can't install from a PPA, then the simplest approach is to install from source into /opt. Apparently, /opt is where one would install optional packages. Additionally, by installing from source with the changed location, each Python version would be completely contained within a directory within /opt. If one ever wants to remove a version, all one needs to do is delete that directory and any associated links.
The first step is to ensure that all dependencies are installed for the currently installed Python version. Run the following once:
$ python --version
Python 2.7.2+
$ sudo apt-get build-dep python2.7
That will install a bunch of dev packages. Which packages get installed will likely depend of each specific system.
The following commands will need to be repeated for each version of Python not already installed. Be sure to replace the X's with the appropriate version numbers. The various versions and download links can be found on the Python download page.
$ wget http://python.org/ftp/python/X.X.X/Python-X.X.X.tgz
$ tar xvfz Python-X.X.X.tgz
$ cd Python-X.X.X
$ ./configure --prefix=/opt/pythonX.X
$ make
$ sudo make install
Of course, these need to be on the path to be useful. So create some links:
$ sudo ln -s /opt/pythonX.X/bin/pythonX.X /usr/bin/pythonX.X
Now, typing pythonX.X on the command line will run Python version X.X:
$ python2.6 --version
Python 2.6.8
$ python3.2 --version
Python 3.2.3
Once all of the Python versions are installed, the tools used to run the tests need to be installed. However, they will only need to be installed for the system's default Python version as virtual environments will be created by tox to run the tests in.
If they're not already installed, download and install virtualenv's dependencies:
$ wget http://python-distribute.org/distribute_setup.py
$ sudo python distribute_setup.py
$ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
$ sudo python get-pip.py
Now, use pip to install virtualenv and tox:
$ sudo pip install virtualenv
$ sudo pip install tox
Some of the tests compare Python-Markdown's output against other implementations (Perl and PHP). However, for the tests to work, insignificant white space in the HTML needs to be normalized. The testing framework uses PyTidyLib to do that. While PyTidyLib will get installed into the individual testing environments, the underlying C library needs to be installed on the system. Some possible names for the library include: 'libtidy', 'libtidy-0.99-0', 'cygtidy-0-99-0', 'tidylib', 'libtidy.dylib', and 'tidy'. Search your system's package manager for the appropriate library and install it. And be sure you're installing the C library, not the command line program. For example, in Ubuntu do:
$ sudo apt-get install libtidy-0.99-0
As tox will install nose in the test virtual environments it creates, nose does not need to be installed globally. However, during development, it may be helpful to quickly run tests in only one environment as one iterates through small changes. Therefore, it is suggested that a development environment be created that includes an installation of nose. To more easily work with the environment, virtualenvwrapper can be helpful.
$ sudo pip install virtualenvwrapper
Then configure virtualenvwrapper as instructed in the docs. At a minimum, add the following lines to ~/.profile or ~/.bashrc
export VIRTUALENV_DISTRIBUTE=true
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh
After saving and sourcing that file (eg: source .profile), create an environment:
$ mkvirtualenv md
(md)$ pip install nose
(md)$ pip install git+https://github.com/waylan/pytidylib.git#egg=PyTidyLib
Note that PyTidyLib is installed from Github rather than PyPI. Unfortunately, the latest release on PyPI is not Python 3 compatible. While the official repo (at https://github.com/countergram/pytidylib) has been updated, the tests have not. Therefore, the more fully tested fork at https://github.com/waylan/pytidylib is recommended.
While tox will create environments for all supported Python versions, it may be helpful to have a second development environment for debugging in Python 3 (if your default is Python 2). Just tell virutalenv which Python to use. For example:
$ mkvirtualenv -p python3.3 md3
Now that everything is set up, the tests can be run. First a copy of the source needs to be cloned from Github:
$ git clone git@github.com:<username>/Python-Markdown.git md
Be sure to replace "<username>" above with our own Github username. You are cloning from your own fork right? How else will you create pull requests to get your changes committed upstream?
If the development virtual environment created earlier isn't active, activate it and run the tests in the default Python version:
$ cd md
$ workon md
(md)$ ./run-tests.py
(md)$ deactivate
You could try the same thing with the "md3" development environment. But running the above commands for each and every supported python version can become tedious. Instead, by running one command, tox, every supported version will have environments created and tests run automatically. Therefore, from the directory which contains the tox.ini file (the repository root), do:
$ tox
The first time it runs, tox will take a bit longer as it needs to create each virtual environment. However, in the future, the test environments will already exist, so the tests will run more quickly.