45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
# 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!
|
|
|
|
```sh
|
|
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:
|
|
|
|
```py
|
|
>>> 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](pwnlib/shellcraft/templates/i386/linux/exit.asm).
|
|
|
|
Additionally, for loading ELF files on-the-fly, the helpers `ELF.from_bytes` and `ELF.from_assembly` are available.
|