Testing an Asterisk dialplan change safely

Define the exact entry point and expected path

Record the channel technology, endpoint or trunk, starting context, received extension, caller identity, expected pattern, priority labels and final destination before editing. Asterisk treats contexts as separation and class-of-service boundaries. A correct extension in an unreachable context does nothing, while a broad include can expose destinations to channels that were never meant to reach them.

Write positive and negative expectations. Include one authorized number, one near-miss that must not match, one denied destination and one invalid or incomplete input. Use a dedicated test context and nonproduction identities where possible. Documentation examples are syntax demonstrations, not a complete authorization or emergency-routing policy.

Resolve exact, pattern, include and switch matching

Asterisk documents the search order within a context as exact extensions, pattern extensions, include statements and switch statements. Inspect every matching candidate rather than assuming file order decides the route. Overlapping patterns or duplicate extensions in included contexts can produce an unexpected match or later-priority fall-through.

Use dialplan show <extension>@<context> for the exact test identity as well as dialplan show <context> for the surrounding boundary. Preserve the matched pattern and priority sequence. Test the shortest, longest and boundary values accepted by a pattern so _X., _! or another broad rule does not silently capture more than intended.

dialplan show <extension>@<context>
dialplan show <context>
core show application Dial
core show channel <channel>

Reload, then prove the loaded dialplan

Asterisk documents dialplan reload as the command that loads changed dialplan without a full service restart. Treat command completion only as evidence that a reload was requested. Inspect the loaded target again and compare the running context, extension and priorities with the proposed change. A saved file, valid editor buffer or clean package template does not prove the active process loaded the intended branch.

Keep configuration ownership explicit. In a FreePBX-managed deployment, do not edit generated dialplan as though it were a durable source. Use the supported custom or module configuration path, apply it through FreePBX and then inspect the generated, loaded dialplan separately.

Trace applications, subroutines and channel ownership

Follow the live channel through context, extension and priority rather than reading only the last console line. GotoIf() can move execution to another label and can terminate the call when its selected target and the fallback i or h extensions do not exist. Gosub() saves a return point and expects Return() when execution must resume. Verify arguments, labels and return behavior on the loaded path.

When Dial() creates outbound channels, the caller channel, each called channel and any bridge have different evidence. A visible called-channel attempt is not an answered bridge. Record the final SIP response, DIALSTATUS, per-channel hangup cause, answer state and media separately; a successful internal call does not prove an outbound or emergency route.

Run a bounded call matrix

Place an allowed call, a deliberately denied destination, a no-answer call and a busy or unavailable call. Add hold, attended transfer, blind transfer or forwarding only when the change can affect those paths. For outbound calls, preserve the normalized number, selected endpoint or trunk, caller identity and returned response. For inbound calls, prove the delivered number and entry context before interpreting later routing.

Use CLI origination only when its channel, endpoint and authorization effects are understood. A generated channel can enter a different context or skip the exact handset, provider, identity and media conditions that the production journey uses. Keep emergency validation within the carrier's approved procedure rather than placing an ordinary live emergency call. When a test creates more than one called channel, use the hangup-cause guide to retain each channel's technology and translated cause alongside DIALSTATUS; do not reduce a parallel or sequential matrix to the final application's summary.

Rollback and repeat the baseline

Retain the prior configuration revision, reload procedure and a baseline result captured before the change. If an expectation fails, record the first divergent context, extension, priority or call leg; restore the previous revision; reload; and repeat the same baseline call. Do not change credentials, endpoint identification, NAT, codecs and dialplan in one recovery step.

After acceptance, remove temporary verbosity, protocol logging and test routes, and retain only redacted evidence. No Asterisk host, dialplan, endpoint, trunk, application path, call, media stream, emergency route or rollback was inspected or tested for this guide.

Test Gosub entry, frame and resumed priority separately

The Gosub diagnostic records the loaded target, arguments, stack frame, branch, Return() and the priority that resumes before judging the later call result.

Include teardown paths in dialplan acceptance

The hangup-handler guide adds per-channel stack order, explicit returns, bounded duration and final record checks to normal answer, rejection, timeout, cancellation and transfer cases.

Add a post-bridge exit matrix to acceptance

Use the after-bridge diagnostic to test owner and peer hangup, bridge removal, transfer, target entry and downstream work as separate stages.

Test speech, pauses and background conditions separately

The TALK_DETECT diagnostic adds a bounded event matrix without presenting documentation-derived thresholds as laboratory validation.

Test a group guard across the full channel lifecycle

Use the channel-count diagnostic below, at and above the threshold, then include parallel setup, answer, transfer, Local optimization and teardown before accepting the policy.

Test one menu selection as a timestamped chain

The BackGround digit diagnostic correlates prompt start and end, received DTMF, option behavior, match candidates, timeout and the first executed destination priority.

Test one multi-contact call without masking inventory errors

The PJSIP_DIAL_CONTACTS diagnostic preserves endpoint, AoR, contacts, dial string and per-leg outcomes before one bounded correction.

Test a codec-offer override without widening endpoint policy

The PJSIP_MEDIA_OFFER diagnostic records handler ownership, requested list, outbound SDP, answer, formats, translation and media before one reversible correction.

Test URI parsing with present, absent and rejected components

Use the focused parser diagnostic to capture the raw redacted value, selector, return contract and final consumer before one reversible correction.

Test hold interception through unhold and teardown

The focused diagnostic captures set timing, exact channel, event delivery, consumer action, music, peer media, unhold and cleanup.

Retest one fax boundary with a bounded document

The Asterisk fax diagnostic freezes module, file, channel, negotiation and session-result evidence before one reversible correction and an approved same-document retest.

Exercise every converted Macro branch on an isolated restore

Use the FreePBX 17 migration guide to test normal return, conditional branches, invalid input, hangup, nested calls and rollback without registering production trunks.

Exercise both contention and failure

Add the dialplan-lock acceptance path to an isolated test: uncontended acquisition, controlled overlap, protected-operation failure, explicit release and unchanged unrelated calls.

Exercise absent, blank and persistent AstDB states

Add the AstDB acceptance path to an isolated test with absent, present-blank, valid, deleted, restart and restore controls.

Test future time branches without moving the host clock

The time-routing acceptance path confines TESTTIME() to an isolated channel and exercises both sides of boundaries, holidays and timezone transitions.

Exercise each variable creation boundary

The variable-scope acceptance path tests one child, intended descendants, both Local halves, Gosub return and relevant transfer-created legs without logging sensitive values.

Test exceptions and return statuses independently

The exception acceptance matrix exercises special-extension precedence, one custom raise and each TRYSTATUS outcome without treating any one branch as proof of a completed call.

Test missing, empty and returned values separately

The lookup acceptance matrix separates exact existence, empty return, non-empty return, one bounded subroutine and downstream outcome.

Test runtime mutation and reload survival separately

The AMI dialplan diagnostic verifies loaded state, one controlled call and the next approved reload as different gates.

Test state shape before testing the destination

The HASH and ARRAY diagnostic exercises absent, blank, changing-key and cardinality controls before interpreting a call result.

Test the list before the destination

The DIALGROUP diagnostic exercises replacement, add, delete, blank-list and unavailable-target controls as separate cases.

Exercise HTTP lookup failure classes independently

The Asterisk CURL diagnostic separates refused connection, timeout, redirect, HTTP rejection, malformed body and missing-key controls.

Exercise empty, changed and misdelimited input

The input-parsing diagnostic defines boundary cases for length, filtering, regex, FIELDQTY and CUT.

Add deprecated-name and explicit-target controls

The upgrade diagnostic tests registered functions, loaded targets, labels, priorities and pattern selection independently.

Add authorized and unauthorized feature-leg controls

The dynamic-feature diagnostic tests loaded mappings, collisions, both legs and application completion separately.

Test the variable consumer after the manager write

The AMI Getvar and Setvar guide keeps an accepted action separate from the later dialplan branch and service outcome.