TESTING.md

Testing

Pwntools makes extensive use of unit tests and integration tests to ensure everything is in working order, and no regressions occur.

Test Suite

To run the test suite, it is best to use Ubuntu 12.04 or 14.04, and run the following commands. Be aware that this will add a user to the machine, and create a public key for SSH login!

bash travis/install.sh
bash travis/ssh_setup.sh
pip install --upgrade --editable .
PWNLIB_NOTERM=1 make -C docs doctest

Testing in Docker

A Dockerfile has been provided which has a clean testing environment with Ubuntu Xenial. It is very similar to the online Travis CI testing environment, but uses a more modern version of Ubuntu.

See travis/docker/README.md for more information.

New Tests

To add a new test to an existing module, just add an inline doctest. If the test needs access to an external module, add the import statement to the testsetup block in the corresponding file in docs/source/<module>.rst.

To add an entirely new module, create a new module.rst and add it to the list in index.rst. The best way to see if your tests are actually being run is to add an intentionally-failing test like:

>>> assert False

Example Test Module

The module pwnlib.testexample exists to demonstrate how everything is tied together. The only files which were modified to add this example module and run its tests automatically are:

• pwnlib/testexample.py
• docs/source/testexample.rst
• docs/source/index.rst

Shellcode and ROP

These are both less easy to test, as they require actually executing code, or loading real binaries. In order to make the process simpler, the runner library was created to wrap common tasks. For an example of testing shellcode with these helpers, see exit.asm.

Additionally, for loading ELF files on-the-fly, the helpers ELF.from_bytes and ELF.from_assembly are available.