Testing Tools

English | 中文

Testing Tools

LiveForge ships with two built-in testing tools: the lf-test integration testing CLI and the gb28181-sim device simulator.

lf-test CLI

tools/lf-test is a comprehensive integration testing tool that validates all server features. It supports push, play, auth, and cluster subcommands with assertion expressions and JSON output for CI integration.

Build

go build -o lf-test ./tools/lf-test

Or run directly:

go run ./tools/lf-test <subcommand> [flags]

Push Test

Push a test stream to the server using any supported protocol.

go run ./tools/lf-test push \
  --protocol rtmp \
  --target rtmp://localhost:1935/live/test \
  --duration 5s \
  --timeout 30s \
  --assert "push.frames_sent>0" \
  --output json

Flag	Default	Description
--protocol	rtmp	Push protocol: rtmp, rtsp, srt, whip, gb28181
--target	— (required)	Target URL (e.g., rtmp://host:1935/live/test)
--duration	0	Push duration; 0 = until source exhausted
--timeout	30s	Overall timeout
--token	—	Auth token
--assert	—	Assertion expression (repeatable)
--output	auto	Output format: human, json (auto-detects from TTY)

Supported push protocols:

Protocol	Target Format
RTMP	rtmp://host:1935/app/stream
RTSP	rtsp://host:8554/app/stream
SRT	srt://host:6000?streamid=publish:/app/stream
WHIP	http://host:8443/webrtc/whip/app/stream
GB28181	host:5060 (SIP server address; --token = API server for invite trigger)

For GB28181 push, lf-test simulates a full GB28181 device: SIP REGISTER, wait for INVITE (triggered via API), and stream RTP/PS media.

Play Test

Play a stream from the server using any supported protocol and collect statistics.

go run ./tools/lf-test play \
  --protocol hls \
  --url http://localhost:8080/live/test.m3u8 \
  --duration 5s \
  --assert "video.fps>=29" \
  --assert "audio.frames>0"

Flag	Default	Description
--protocol	rtmp	Play protocol: rtmp, rtsp, srt, whep, httpflv, wsflv, hls, llhls, dash
--url	— (required)	Stream URL
--duration	0	Play duration; 0 = until server closes
--timeout	30s	Overall timeout
--token	—	Auth token
--assert	—	Assertion expression (repeatable)
--output	auto	Output format

The play command collects stream statistics including video FPS, audio frame count, bitrate, codec info, and latency metrics.

Auth Test

Test authentication flows for publish and subscribe.

go run ./tools/lf-test auth \
  --target rtmp://localhost:1935/live/test \
  --token "eyJhbGciOiJIUzI1NiIs..."

Cluster Test

Automatically launch a multi-node cluster, push a stream, and validate relay.

go run ./tools/lf-test cluster \
  --topology origin-edge \
  --relay-protocol srt \
  --push-protocol rtmp \
  --play-protocol hls \
  --duration 5s \
  --assert "cluster.relay_ms<500"

Flag	Default	Description
--topology	origin-edge	Topology: origin-edge, origin-multi-edge, origin-center-edge
--push-protocol	rtmp	Protocol for pushing to origin
--play-protocol	rtmp	Protocol for playing from edge
--relay-protocol	rtmp	Protocol for cluster relay links
--stream	live/test	Stream key
--duration	5s	Play duration
--edges	1	Number of edge nodes (for origin-multi-edge)
--binary	auto-detect	Path to liveforge binary
--timeout	120s	Overall timeout

The cluster command:

1. Builds liveforge if --binary not specified (looks for ./bin/liveforge)
2. Generates YAML configs for each node with unique ports
3. Launches origin, center (if applicable), and edge processes
4. Pushes a test stream to origin
5. Plays from edge and collects metrics
6. Reports results and cleans up

Assertion Expressions

All subcommands support --assert for declarative validation:

--assert "push.frames_sent>0"
--assert "video.fps>=29"
--assert "audio.frames>0"
--assert "cluster.relay_ms<500"

Failed assertions cause a non-zero exit code, making them suitable for CI pipelines.

JSON Output

Use --output json for machine-readable output:

go run ./tools/lf-test push \
  --protocol rtmp \
  --target rtmp://localhost:1935/live/test \
  --duration 3s \
  --output json

gb28181-sim (Device Simulator)

tools/gb28181-sim simulates a GB28181 IPC camera for acceptance testing. It performs the full GB28181 device lifecycle.

Usage

go run ./tools/gb28181-sim [flags]

Flag	Default	Description
-server	127.0.0.1:5060	LiveForge SIP server address
-device-id	34020000001110000001	Simulated device ID (20-digit GB code)
-domain	3402000000	SIP domain
-server-id	34020000002000000001	Server device ID
-transport	udp	SIP transport: udp or tcp
-local-port	5061	Local SIP port
-keepalive	30s	Keepalive interval
-fps	25	Video frame rate for RTP streaming
-no-audio	false	Disable audio generation

What It Does

1. SIP REGISTER — Registers with the LiveForge SIP server
2. Periodic keepalive — Sends keepalive MESSAGE at configured interval
3. Catalog response — Responds to catalog queries with simulated channel info (camera name, manufacturer "Hikvision", GPS coordinates)
4. INVITE handling — On incoming INVITE, starts RTP/PS streaming (H.264 + AAC via ffmpeg)
5. PTZ acknowledgment — Logs received PTZ control commands
6. BYE handling — Stops streaming on BYE

Requirements

• ffmpeg must be in PATH (used to generate test H.264+AAC media)

Example Workflow

# Terminal 1: Start LiveForge
./liveforge -c configs/liveforge.yaml

# Terminal 2: Start simulator
go run ./tools/gb28181-sim -server 127.0.0.1:5060

# Terminal 3: Trigger live view via API
curl -X POST http://localhost:8090/api/v1/gb28181/channels/34020000001110000001/play

# Terminal 4: Watch the stream
ffplay http://localhost:8080/gb28181/34020000001110000001.flv

testkit Library

tools/testkit/ contains reusable Go packages used by both lf-test and integration tests:

Package	Purpose
push/	Protocol-specific pushers (RTMP, RTSP, SRT, WHIP, GB28181)
play/	Protocol-specific players (RTMP, RTSP, SRT, WHEP, HTTP-FLV, WS-FLV, HLS, LL-HLS, DASH)
cluster/	Cluster topology builders and process management
analyzer/	Stream statistics collector (FPS, bitrate, frame counts)
report/	Structured push/play report generation
source/	Test media source (FLV file reader with loop support)
auth/	Auth testing utilities
testutil/	Server lifecycle helpers for integration tests

These packages can be imported directly in Go integration tests:

import "github.com/im-pingo/liveforge/tools/testkit/push"
import "github.com/im-pingo/liveforge/tools/testkit/play"