From f3e3a64ec278c5c3964b4040cd3f5fe3398a9601 Mon Sep 17 00:00:00 2001 From: Michael Vetter Date: Fri, 6 Mar 2026 09:45:51 +0100 Subject: [PATCH] docs: Add a section explaining how to write functional tests --- CONTRIBUTING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e645bb94..d6e892c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -191,6 +191,28 @@ Using Autotools: 3. To run manually: `./tests/functionaltests/functionaltests` 4. To run a specific test manually: `CMOCKA_TEST_FILTER=test_name ./tests/functionaltests/functionaltests` +### Writing functional tests +Functional tests simulate real world usage by running Profanity and interacting with it. They verify Profanitys responses to an XMPP server. + +They are located in `tests/functionaltests/`. + +#### Helper Functions +We provide a set of helper functions: +- `prof_input(const char* input)`: Sends a command or message to Profanity. +- `prof_output_regex(const char* regex)`: Verifies that Profanity's output matches the given regular expression. +- `prof_output_exact(const char* text)`: Verifies that Profanity's output exactly matches the given text. +- `prof_connect()`: Connects Profanity to the simulated stabber server. +- `stbbr_for_id(const char* id, const char* xml)`: Tells stabber to respond with `xml` when it receives a stanza with the given `id`. +- `stbbr_for_query(const char* xmlns, const char* xml): Tells the server to respond with xml whenever a query for a specific namespace is received. + +To see the complete list check `proftest.h`. + +#### Adding a new test +1. Create a new test file (`test_new_feature.c` and `test_new_feature.h`) in `tests/functionaltests/`. +2. Define your test functions using the `void test_name(void** state)` signature. +3. Use the `PROF_FUNC_TEST(test_name)` macro to register your test in `tests/functionaltests/functionaltests.c`. This macro automatically handles the setup (`init_prof_test`) and teardown (`close_prof_test`) for each test. +4. Add the new source file to `functionaltest_sources` in both `meson.build` and `Makefile.am`. + ### Valgrind We provide a suppressions file `prof.supp`. It is a combination of the suppressions for shipped with glib2, python and custom rules.