vnctalk-prosody/tests/README.md

VNCtalk Prosody Verification Test Suite

This directory contains an integration-test suite that verifies whether a running XMPP server conforms to the VNCtalk Prosody behaviour requirements.

Prerequisites

You need Python 3.10+ with the venv module.

1. Create the virtualenv

Create it inside the repo (recommended) so it is isolated and reproducible:

cd /path/to/vnctalk-prosody
python3 -m venv tests/venv

Or use a hidden .venv at repo root:

python3 -m venv .venv

2. Activate the virtualenv

Linux / macOS:

source tests/venv/bin/activate

Windows (PowerShell):

tests/venv/Scripts/Activate.ps1

Windows (cmd.exe):

tests/venv/Scripts/activate.bat

3. Install dependencies

pip install slixmpp pytest pytest-asyncio aiohttp

The dependencies are also captured in tests/pytest.ini (config only). If you want to pin versions for CI, create a tests/requirements.txt and run pip install -r tests/requirements.txt.

4. Verify the installation

pytest tests/ --collect-only -c tests/pytest.ini

You should see 27 tests collected. If the collection fails with an asyncio error, make sure you are passing -c tests/pytest.ini (it sets asyncio_mode = auto).

Configuration

Tests are configured via environment variables or CLI options.

Environment variables

Variable	Default	Description
XMPP_HOST	localhost	C2S hostname
XMPP_PORT	5222	C2S port
XMPP_JID	(empty)	Test account JID
XMPP_PASSWORD	(empty)	Test account password
XMPP_DOMAIN	example.com	XMPP domain
BOSH_URL	(empty)	BOSH endpoint URL
WS_URL	(empty)	WebSocket endpoint URL
REST_URL	(empty)	mod_http_rest URL
MUC_DOMAIN	(empty)	MUC component domain
ADMIN_TELNET_HOST	127.0.0.1	Admin telnet host
ADMIN_TELNET_PORT	5582	Admin telnet port

CLI options

All env vars can be overridden on the command line:

pytest tests/ \
  --xmpp-host=192.168.1.10 \
  --xmpp-jid=user@example.com \
  --xmpp-password=secret \
  --xmpp-domain=example.com \
  --muc-domain=conference.example.com \
  --bosh-url=http://192.168.1.10:5280/http-bind \
  --ws-url=ws://192.168.1.10:5280/xmpp-websocket \
  --rest-url=http://192.168.1.10:5280/rest

Running

The test suite includes a pytest.ini with asyncio_mode = auto. Run from the repo root or point to the config:

Run all tests

pytest tests/ -v -c tests/pytest.ini

Skip live-connection tests (dry-run infrastructure checks only)

pytest tests/ -v --skip-live -c tests/pytest.ini

Run a specific test file

pytest tests/test_01_core.py -v -c tests/pytest.ini

Run with a running Prosody container

If you built the Docker image and started it with test.sh, expose the ports and run:

export XMPP_HOST=127.0.0.1
export XMPP_JID=admin@example.com
export XMPP_PASSWORD=<the-password-from-your-auth-backend>
export XMPP_DOMAIN=example.com
export MUC_DOMAIN=conference.example.com
export BOSH_URL=http://127.0.0.1:5280/http-bind
export WS_URL=ws://127.0.0.1:5280/xmpp-websocket
export REST_URL=http://127.0.0.1:5280/rest

pytest tests/ -v

Test Coverage

File	What it checks
test_01_core.py	C2S auth, disco features (MAM, carbons), BOSH/WebSocket reachability, REST injection
test_02_muc.py	MUC disco, room creation, MUC MAM query, auto-member on invite, vdata disco
test_03_vnctalk.py	vCard fallback, avatar upload trigger, timestamp stamps, receipts, broadcast component
test_04_infra.py	Admin telnet banner, healthcheck exit-code contract, port reachability

Notes

• Tests that require a live XMPP account are skipped automatically if --xmpp-jid or --xmpp-password are empty (or if --skip-live is used).
• MUC tests create temporary rooms. If the test account is not allowed to create rooms, those tests will skip or fail.
• The REST injection test sends a dummy stanza; a 201 or 422 response is considered acceptable ( Prosody may reject unroutable stanzas with 422).
• The healthcheck test inspects the script source for the required exit 2 semantics rather than executing it inside the container.