# Functional tests

`tests/functionaltests/` exercises a real cproof binary under a PTY against a
real (test) XMPP server.

## Files

| File | Role |
|---|---|
| `functionaltests.c` | Runner (entry point). |
| `proftest.c/h` | Fixture: spawn cproof under PTY, drive XMPP server, assertions. |
| `test_<feature>.c` | Per-feature suites. |

Existing suites (grep for `test_*.c`):

- Connection / disconnection: `test_connect.c`, `test_disconnect.c`,
  `test_autoping.c`, `test_ping.c`.
- Messaging: `test_message.c`, `test_chat_session.c`, `test_carbons.c`,
  `test_receipts.c`, `test_history.c`.
- Presence and roster: `test_presence.c`, `test_roster.c`,
  `test_lastactivity.c`.
- Discovery: `test_disco.c`, `test_software.c`.
- MUC: `test_muc.c`, `test_rooms.c`.
- Storage: `test_export_import.c`.

## Prerequisites

- A test XMPP server reachable from the harness (typically a local Prosody
  instance configured for the tests).
- A pre-baked `.profrc` (recent perf work pre-bakes this for speed — see
  cproof commit `f84ed1bf6` for context).
- PTY availability (`/dev/ptmx` on Linux).

## Running

Functional tests are not part of `make check` (which runs unit tests only).
They are built and invoked via a separate target in `tests/functionaltests/`
— inspect `tests/functionaltests/Makefile.am` for the current target name and
arguments.

Recent perf work (commit `f84ed1bf6`) added:
- Profrc pre-baking — fixture writes a known-good `.profrc` once, not per-test.
- pty-close shutdown — fixture closes the PTY to terminate cproof faster than
  signalling.
- Parallel port pools — separate XMPP servers / ports per parallel suite.

## When to add functional vs unit

| Test what | Where |
|---|---|
| Pure logic, internal API, given a state. | Unit. |
| Stanza serialization / parsing round-trip with real libstrophe. | Functional. |
| Connection state machine across multiple network events. | Functional. |
| UI rendering (visible output). | **Neither** (UI stubbed in unit; not asserted in functional). |

## Failure-mode notes

- A leaked / orphan cproof process between suites poisons later runs. The
  fixture aggressively kills children — but if you abort a test by hand,
  `pkill -f tests/functionaltests` first.
- Port-pool exhaustion under parallelism: bump the pool size, do not lower
  `-jN`.