- [] If my change adds new code, [adequate tests](docs/testing.md) have been added.

PYTEST_PARAMETERS := --verbose --forked --numprocesses=$(NB_CORES)

TMPDIR=$(TMPDIR) python3 -m pytest $(PYTEST_PARAMETERS) -k "not benchmark"

TMPDIR=$(TMPDIR) python3 -m pytest $(PYTEST_PARAMETERS) -k $@

python3 -m pylint $(PYLINT_TEST_PARAMETERS) $(wildcard tests/*.py tests/*/*.py)

This page describes how GEF testing is done. Any new command/functionality must receive adequate testing to be merged. Also PR failing CI (test + linting) won't be merged either.

All the prerequisite packages are in `requirements.txt` file at the root of the project. So running

python -m pip install -r requirements.txt --user -U

is enough to get started.

For testing GEF on the architecture on the host running the tests (most cases), simply run

cd /root/of/gef

make test

Otherwise, `make` can be adjusted to :

- run one test/one group of tests specifically

- eg. `make test_cmd_heap` will trigger all the test functions for the `heap` command

- run for a different architecture

- eg. on x86, you can test x86 too with `TARGET=i686 make TARGET=i686 test`

Unless a specific test is mentioned, the command `make test` will run all the non-benchmark related tests.

At the end, a summary of explanation will be shown, clearly indicating the tests that have failed: for instance:

You can then use `pytest` directly to help you fix each error specifically.

GEF entirely relies on [`pytest`](https://pytest.org) for its testing. Refer to the project documentation for details.

Adding a new command __requires__ for extensive testing in a new dedicated test module that should be located in `/root/of/gef/tests/commands/my_new_command.py`

A skeleton of a test module would look something like:

from tests.utils import GefUnitTestGeneric, gdb_run_cmd, gdb_start_silent_cmd

class MyCommandCommand(GefUnitTestGeneric):

"""`my-command` command test module"""

def test_cmd_my_command(self):

# `my-command` is expected to fail if the session is not active

self.assertFailIfInactiveSession(gdb_run_cmd("my-command"))

# `my-command` should never throw an exception in GDB when running

res = gdb_start_silent_cmd("my-command")

self.assertNoException(res)

# it also must print out a "Hello World" message

self.assertIn("Hello World", res)

When running your test, you can summon `pytest` with the `--pdb` flag to enter the python testing environment to help you get more information about the reason of failure.

You can use the Makefile at the root of the project to get the proper linting settings. For most cases, the following command is enough:

cd /root/of/gef

make lint

Benchmarking relies on `pytest-benchmark` and is experimental for now.

You can run all benchmark test cases as such:

cd /root/of/gef

pytest -k benchmark

which will return (after some time) an execution summary