Skip to content
Phone Guides

Plan repeatable integration tests for Asterisk

An Asterisk integration test should state which part of a call it checks, the expected result and the evidence it keeps. Unit tests, the Asterisk Test Suite, SIPp and a call through a real carrier cover different boundaries. A passing test at one boundary does not prove the next one.

Source-reviewed, 20 October 2026. This guide follows the current Asterisk Test Suite documentation and SIPp reference. Phone Guides has not run these tests against a PBX. Use an isolated development instance with a named Asterisk build, configuration and tool versions; do not point synthetic traffic at production or a carrier without explicit test authorization.

Pick a test at the boundary you need

Test layer Useful for Does not establish
Asterisk unit framework Internal code behavior and individual interfaces A complete dialplan call or carrier interoperability
Asterisk Test Suite Functional behavior across Asterisk modules, with controlled prerequisites and external protocol tools Your exact deployed configuration, phones, NAT, carrier or customer traffic
SIPp scenario SIP requests and responses, dialog steps, timers, authentication exchanges and selected RTP behavior Asterisk internals, a human's audio experience or carrier acceptance
Application tests with fake ARI/provider services State transitions, authorization, retries, interruption, timeout and cleanup in your adapter Live API behavior, real-time audio quality or an actual ARI/media path
End-to-end call The chosen endpoint, network, PBX build, carrier and service together Other endpoints, routes, regions, loads or account settings that were not part of the test

Asterisk describes its unit framework as bottom-up, the Test Suite as functional testing across modules, and system testing as a wider interaction check. The Test Suite starts Asterisk instances and coordinates external protocol tools. Treat its result as evidence about the tested build and preconditions, not as a general guarantee for every release. Asterisk testing overview

Write the call contract before the scenario

Draw the path as explicit steps. A common example is: SIPp client sends an INVITE, Asterisk authenticates it, the dialplan selects a context, a controlled destination answers, media is negotiated, and BYE closes both legs. For an ARI application, add the Stasis entry, channel and bridge state, application event handling, media session, and cleanup. Name the exact entry and exit conditions at each boundary.

For each case, record:

  • Asterisk version or commit, loaded modules, configuration revision and test-suite revision.
  • SIP transport, endpoint role, codec/SDP, authentication setup, dialplan context and destination.
  • The stimulus, expected SIP response and expected Asterisk/application state.
  • A finite timeout, a pass condition, a fail condition and the artefact needed to diagnose a failure.

Keep configuration and test inputs in version control without passwords, private keys, customer numbers or personal recordings. Use dedicated test identities and synthetic data. Store only the SIP trace, Asterisk log, test output or packet capture needed for the result, with access and deletion rules appropriate to that data.

Build a small functional matrix

Start with one successful path, then add one changed condition per case. For a basic inbound call, useful cases include:

Case Stimulus Check
Answer and hang up Valid INVITE, answer, ACK, then BYE Expected response sequence, both channel legs end, no channel remains
Unknown or unauthorised caller Invalid identity or rejected credentials Rejection occurs before protected dialplan actions; no unintended destination is reached
Missing destination Valid call to an unconfigured extension The documented failure route is taken and the caller receives a bounded response
No answer Destination does not answer before the configured limit Timeout route runs once and all channels are cleared
Caller abandons Send CANCEL before answer, or BYE after answer Correct leg ends; no later application action or orphaned channel remains
DTMF or transfer Send the configured keypad input or exercise the transfer path The intended branch or transfer occurs once and preserves the required call state
Media negotiation failure Offer a codec or media address outside the allowed test setup Failure is visible and follows the specified fallback; do not infer two-way audio from a 200 OK

For each case, assert more than a SIP status code where the design depends on application state. Check the dialplan result, AMI/ARI event sequence, channel and bridge cleanup, and any controlled business-service call. A timeout case should verify that a late response cannot resurrect a finished call or repeat a side effect.

Use the Asterisk Test Suite and SIPp for their intended jobs

The Asterisk Test Suite supports listing and selecting tests, including selection by tags. Its configuration uses tests.yaml to locate tests and test-config.yaml for an individual test; current documentation recommends the sample YAML and component framework. The older run-test script method and the separate Python-test walkthrough are marked deprecated, so do not copy old tutorials as a current starter. Read the current install/run instructions for the Asterisk branch and test-suite revision you select. Running the Asterisk Test Suite, Test Suite configuration, component framework

SIPp can generate SIP calls against a remote system and run XML call scenarios. A scenario can require particular responses, wait for a message with a timeout, branch on a result and record response-time measurements. The Asterisk Test Suite itself uses SIPp for some SIP tests and includes helpers for coordinating it with Asterisk instances. Begin with a finite call count and one scenario; inspect SIPp's exit status and traces alongside Asterisk's own logs. Asterisk tests with SIPp, SIPp scenario guide, SIPp main features and exit codes

SIPp is also used for load tests, but its timing depends on the host and its event loop. The SIPp guide advises limiting traces for performance runs and checking its scheduling limits; a measured response time can reflect SIPp's timing resolution. Do not use one load run to claim a calls-per-server limit. State the host, traffic profile, Asterisk build, codec, media path and measurement method, then repeat the run while observing both the generator and PBX. SIPp performance testing

Test AI and ARI logic without exposing a live service

For an AI media bridge, first test the application state machine with fake provider and fake ARI responses. Cover session start, audio framing conversion, partial and final transcripts, caller interruption, provider disconnect, malformed events, tool requests, duplicate events, transfer, timeout and cleanup. Use the dated AI provider contract checklist to select the event names, versions and audio constraints for the provider being faked; do not assume that one provider's script applies to another. A fake can prove your code responds to a scripted event; it cannot prove that the provider emits that event in a live call or that Asterisk and the provider interoperate on the network.

Then add a controlled Asterisk path using the exact transport and module release under review. Track a single call/session identifier across the Asterisk channel, bridge, media connection and provider session. Verify that hangup and reconnect clear each resource and that retries do not repeat a business action. Use synthetic audio and test accounts; keep provider credentials out of traces and logs. See secure AI actions and human handoff and live voice agents with Asterisk.

Advance from simulation to a live call in stages

  1. Run deterministic unit and application tests with in-memory fakes.
  2. Run the relevant Asterisk Test Suite checks on an isolated build and save the exact test selection and result.
  3. Run a finite SIPp scenario against that isolated system; inspect signaling, media negotiation, Asterisk state and cleanup.
  4. Place a manual call between approved test endpoints on the intended network. Check two-way audio, DTMF, transfer, caller hangup and recovery.
  5. Test the carrier route only with a test number and carrier authorization. Record the exact trunk, number type, region and conditions. Do not send test calls to emergency services.

Keep a short result record: test date; Asterisk and FreePBX versions if used; modules and configuration revision; SIPp and test-suite versions; scenario or test IDs; endpoint, network and carrier scope; pass/fail output; known gaps. Redact credentials, authentication headers, phone numbers and personal data before sharing a trace.

Sources and limits

This is a test-planning guide, not a prebuilt suite, FreePBX certification or carrier acceptance test. Pin the product and test-suite revisions before following setup instructions; upstream documentation and requirements change.