fakepbx

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2026 License: MIT Imports: 14 Imported by: 0

README

fakepbx

CI Go Reference Go Report Card

In-process SIP server for Go tests. Real SIP over loopback — no Docker, no Asterisk, no hardcoded ports.

Why?

If you're building a SIP client, softphone, or any VoIP application in Go, you need something to talk to during tests. The usual options are painful:

  • Spin up Asterisk/FreeSWITCH in Docker — slow startup, complex config files, brittle networking, extra CI dependencies, and you still can't easily script "send 180 Ringing, wait 500ms, then 486 Busy Here."
  • Point at a shared staging PBX — flaky, non-deterministic, can't run tests in parallel, breaks when someone else is using it.
  • Mock at the SIP library level — fast, but you're not testing real SIP anymore. Your mocks drift from reality.

FakePBX gives you a real SIP server that lives inside your test process. It speaks actual SIP over UDP on loopback — your code sends and receives real SIP messages — but you control every response programmatically. No config files, no containers, no network setup.

pbx := fakepbx.NewFakePBX(t) // real SIP server, ready in <1ms

Each test gets its own server on an OS-assigned port, torn down automatically via t.Cleanup. Tests run in parallel without conflicts. CI just needs go test.

What can it do?

You script the PBX side of any SIP flow step by step. Wraps sipgo under the hood.

Install

go get github.com/x-phone/fakepbx

Requires Go 1.23+.

Quick Start

func TestMyUA_ReceivesCall(t *testing.T) {
    pbx := fakepbx.NewFakePBX(t) // starts on 127.0.0.1:<random>

    pbx.OnInvite(func(inv *fakepbx.Invite) {
        inv.Trying()
        inv.Ringing()
        inv.Answer(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))
    })

    // Point your SIP UA at pbx.Addr() and dial pbx.URI("1002")
}

No handler? FakePBX auto-answers everything with 200 OK.

Examples

Busy Rejection
pbx := fakepbx.NewFakePBX(t)
pbx.AutoBusy() // all INVITEs get 486 Busy Here
Early Media
pbx.OnInvite(func(inv *fakepbx.Invite) {
    inv.Trying()
    inv.EarlyMedia(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU)) // 183
    time.Sleep(100 * time.Millisecond)
    inv.Answer(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))     // 200
})
CANCEL Handling
pbx.OnInvite(func(inv *fakepbx.Invite) {
    inv.Trying()
    inv.Ringing()
    // Block until caller cancels or timeout
    if inv.WaitForCancel(time.Second) {
        t.Log("caller cancelled")
    }
})
PBX Hangs Up Mid-Call
var call *fakepbx.ActiveCall
pbx.OnInvite(func(inv *fakepbx.Invite) {
    inv.Trying()
    call = inv.Answer(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))
})

// ... establish the call, then:
call.SendBye(context.Background()) // PBX initiates hangup
Re-INVITE (Hold)
holdSDP := fakepbx.SDPWithDirection("127.0.0.1", 20000, "sendonly", fakepbx.PCMU)
call.SendReInvite(context.Background(), holdSDP)
REFER (Call Transfer)
pbx.OnRefer(func(ref *fakepbx.Refer) {
    fmt.Println("transfer to:", ref.ReferTo())
    ref.Accept() // 202 Accepted
})
Registration with Auth Challenge
pbx.OnRegister(func(reg *fakepbx.Register) {
    if pbx.RegisterCount() <= 1 {
        reg.Challenge("fakepbx", "testnonce123") // 401
        return
    }
    reg.Accept() // 200
})
Request Inspection
// After running your test flow:
last := pbx.LastInvite()
byes := pbx.Requests(sip.BYE)

// Polling waiters (never hang — always time out):
pbx.WaitForInvite(1, time.Second)  // blocks until 1 INVITE arrives
pbx.WaitForBye(1, time.Second)     // blocks until 1 BYE arrives
Parallel Tests
func TestA(t *testing.T) {
    t.Parallel()
    pbx := fakepbx.NewFakePBX(t) // own port, no conflicts
    _ = pbx
}

func TestB(t *testing.T) {
    t.Parallel()
    pbx := fakepbx.NewFakePBX(t) // different port
    _ = pbx
}

API Overview

Type Purpose
FakePBX The SIP server. Create with NewFakePBX(t).
Invite Handle for INVITE. Trying(), Ringing(), Answer(), Reject(), WaitForCancel()
ActiveCall Returned by Answer(). SendBye(), SendReInvite(), SendNotify()
Register Handle for REGISTER. Accept(), Challenge(), Reject()
Bye Handle for BYE. Accept(), Reject()
Cancel Handle for CANCEL (notification-only). Request()
Refer Handle for REFER. Accept(), Reject(), ReferTo()
Options Handle for OPTIONS. Accept(), Reject()
Info Handle for INFO. Accept(), Reject(), Body()
Message Handle for MESSAGE. Accept(), Reject(), Body()
Subscribe Handle for SUBSCRIBE. Accept(), Reject(), Event()
Ack Handle for ACK. Request(), SDP()
SDP() Minimal SDP generator for test responses
Codec RTP codec descriptor. Predefined: PCMU, PCMA, G722
Options
fakepbx.NewFakePBX(t,
    fakepbx.WithTransport("udp"),       // default
    fakepbx.WithUserAgent("MyPBX/1.0"),
    fakepbx.WithAuth("user", "pass"),   // digest auth (RFC 2617)
)
Convenience Presets
pbx.AutoAnswer(sdp)             // 100 → 180 → 200 OK
pbx.AutoBusy()                  // 100 → 486 Busy Here
pbx.AutoReject(503, "Unavail")  // 100 → 503

Default Behaviors

When no handler is registered:

Request Default Response
REGISTER 200 OK
INVITE 100 Trying → 200 OK + SDP
ACK absorbed silently
BYE 200 OK
CANCEL 200 OK (+ 487 to INVITE)
REFER 202 Accepted
OPTIONS 200 OK
INFO 200 OK
MESSAGE 200 OK
SUBSCRIBE 200 OK

License

MIT

Documentation

Overview

Package fakepbx provides an in-process SIP server (UAS) for testing.

It wraps sipgo to create a real SIP server bound to 127.0.0.1 on an ephemeral port. Tests get full programmatic control over SIP call flows — INVITE, REGISTER, BYE, CANCEL, REFER, OPTIONS, INFO, MESSAGE, SUBSCRIBE — without Docker, external processes, or hardcoded ports.

Basic usage: 

pbx := fakepbx.NewFakePBX(t)
pbx.OnInvite(func(inv *fakepbx.Invite) {
    inv.Trying()
    inv.Ringing()
    inv.Answer(fakepbx.SDP("127.0.0.1", 20000, fakepbx.PCMU))
})
// Point your SIP UA at pbx.Addr() and dial pbx.URI("1002")

The server is stopped automatically via testing.TB.Cleanup.

Index

Constants

This section is empty.

Variables

View Source 
var (
	PCMU = Codec{PayloadType: 0, Name: "PCMU", ClockRate: 8000}
	PCMA = Codec{PayloadType: 8, Name: "PCMA", ClockRate: 8000}
	G722 = Codec{PayloadType: 9, Name: "G722", ClockRate: 8000}
)

Common codecs.

Functions

func SDP 

func SDP(ip string, port int, codecs ...Codec) []byte

SDP returns a minimal valid SDP body for test responses. If no codecs are specified, defaults to PCMU.

func SDPWithDirection 

func SDPWithDirection(ip string, port int, direction string, codecs ...Codec) []byte

SDPWithDirection returns SDP with a specific media direction attribute. Direction should be "sendonly", "recvonly", "sendrecv", or "" for no direction line.

Types

type Ack 

type Ack struct {
	// contains filtered or unexported fields
}

Ack is the handle passed to OnAck handlers.

func (*Ack) Request 

func (a *Ack) Request() *sip.Request

Request returns the original SIP ACK request.

func (*Ack) SDP 

func (a *Ack) SDP() []byte

SDP returns the SDP body from the ACK, or nil.

type ActiveCall 

type ActiveCall struct {
	// contains filtered or unexported fields
}

ActiveCall is returned by Invite.Answer(). It lets tests simulate PBX-side mid-call actions.

func (*ActiveCall) SendBye 

func (c *ActiveCall) SendBye(ctx context.Context) error

SendBye makes the PBX hang up the call.

func (*ActiveCall) SendNotify 

func (c *ActiveCall) SendNotify(ctx context.Context, eventType, body string) error

SendNotify sends a NOTIFY (e.g., after REFER to report transfer status).

func (*ActiveCall) SendReInvite 

func (c *ActiveCall) SendReInvite(ctx context.Context, sdp []byte) error

SendReInvite sends a re-INVITE with new SDP (hold, codec change, etc.).

type Bye 

type Bye struct {
	// contains filtered or unexported fields
}

Bye is the handle passed to OnBye handlers.

func (*Bye) Accept 

func (b *Bye) Accept()

Accept sends 200 OK.

func (*Bye) Reject 

func (b *Bye) Reject(code int, reason string)

Reject sends a non-2xx final response (e.g. 481 Call/Transaction Does Not Exist).

func (*Bye) Request 

func (b *Bye) Request() *sip.Request

Request returns the original SIP BYE request.

type Cancel 

type Cancel struct {
	// contains filtered or unexported fields
}

Cancel is the handle passed to OnCancel handlers.

Cancel handlers are notification-only: the SIP stack automatically sends 200 OK to the CANCEL and 487 Request Terminated to the original INVITE. The handler lets tests observe that cancellation occurred but cannot influence the response.

func (*Cancel) Request 

func (c *Cancel) Request() *sip.Request

Request returns the original SIP CANCEL request.

type Codec 

type Codec struct {
	PayloadType int
	Name        string
	ClockRate   int
}

Codec represents an RTP codec for SDP generation.

type FakePBX 

type FakePBX struct {
	// contains filtered or unexported fields
}

FakePBX is an in-process SIP UAS for testing.

func NewFakePBX 

func NewFakePBX(t testing.TB, opts ...Option) *FakePBX

NewFakePBX creates and starts a FakePBX on 127.0.0.1:0 (UDP). The server is stopped automatically via t.Cleanup.

func (*FakePBX) AckCount 

func (pbx *FakePBX) AckCount() int

AckCount returns the number of ACK requests received.

func (*FakePBX) Addr 

func (pbx *FakePBX) Addr() string

Addr returns the bound address ("127.0.0.1:PORT").

func (*FakePBX) AutoAnswer 

func (pbx *FakePBX) AutoAnswer(sdp []byte)

AutoAnswer makes the PBX answer all INVITEs with: 100 -> 180 -> 200 OK + SDP.

func (*FakePBX) AutoBusy 

func (pbx *FakePBX) AutoBusy()

AutoBusy makes the PBX reject all INVITEs with: 100 -> 486 Busy Here.

func (*FakePBX) AutoReject 

func (pbx *FakePBX) AutoReject(code int, reason string)

AutoReject makes the PBX reject all INVITEs with the given code and reason.

func (*FakePBX) ByeCount 

func (pbx *FakePBX) ByeCount() int

ByeCount returns the number of BYE requests received.

func (*FakePBX) CancelCount 

func (pbx *FakePBX) CancelCount() int

CancelCount returns the number of CANCEL requests received.

func (*FakePBX) InfoCount 

func (pbx *FakePBX) InfoCount() int

InfoCount returns the number of INFO requests received.

func (*FakePBX) InviteCount 

func (pbx *FakePBX) InviteCount() int

InviteCount returns the number of INVITE requests received.

func (*FakePBX) LastInvite 

func (pbx *FakePBX) LastInvite() *sip.Request

LastInvite returns the most recent INVITE request, or nil.

func (*FakePBX) LastRegister 

func (pbx *FakePBX) LastRegister() *sip.Request

LastRegister returns the most recent REGISTER request, or nil.

func (*FakePBX) MessageCount 

func (pbx *FakePBX) MessageCount() int

MessageCount returns the number of MESSAGE requests received.

func (*FakePBX) OnAck 

func (pbx *FakePBX) OnAck(h func(*Ack))

OnAck sets the handler for incoming ACK requests.

func (*FakePBX) OnBye 

func (pbx *FakePBX) OnBye(h func(*Bye))

OnBye sets the handler for incoming BYE requests.

func (*FakePBX) OnCancel 

func (pbx *FakePBX) OnCancel(h func(*Cancel))

OnCancel sets the handler for incoming CANCEL requests.

func (*FakePBX) OnInfo 

func (pbx *FakePBX) OnInfo(h func(*Info))

OnInfo sets the handler for incoming INFO requests.

func (*FakePBX) OnInvite 

func (pbx *FakePBX) OnInvite(h func(*Invite))

OnInvite sets the handler for incoming INVITE requests.

func (*FakePBX) OnMessage 

func (pbx *FakePBX) OnMessage(h func(*Message))

OnMessage sets the handler for incoming MESSAGE requests.

func (*FakePBX) OnOptions 

func (pbx *FakePBX) OnOptions(h func(*Options))

OnOptions sets the handler for incoming OPTIONS requests.

func (*FakePBX) OnRefer 

func (pbx *FakePBX) OnRefer(h func(*Refer))

OnRefer sets the handler for incoming REFER requests.

func (*FakePBX) OnRegister 

func (pbx *FakePBX) OnRegister(h func(*Register))

OnRegister sets the handler for incoming REGISTER requests.

func (*FakePBX) OnSubscribe 

func (pbx *FakePBX) OnSubscribe(h func(*Subscribe))

OnSubscribe sets the handler for incoming SUBSCRIBE requests.

func (*FakePBX) OptionsCount 

func (pbx *FakePBX) OptionsCount() int

OptionsCount returns the number of OPTIONS requests received.

func (*FakePBX) ReferCount 

func (pbx *FakePBX) ReferCount() int

ReferCount returns the number of REFER requests received.

func (*FakePBX) RegisterCount 

func (pbx *FakePBX) RegisterCount() int

RegisterCount returns the number of REGISTER requests received.

func (*FakePBX) Requests 

func (pbx *FakePBX) Requests(method sip.RequestMethod) []RecordedRequest

Requests returns all recorded requests of the given SIP method.

func (*FakePBX) SIPAddr 

func (pbx *FakePBX) SIPAddr() string

SIPAddr returns the address in SIP format: "127.0.0.1:PORT;transport=udp"

func (*FakePBX) SubscribeCount 

func (pbx *FakePBX) SubscribeCount() int

SubscribeCount returns the number of SUBSCRIBE requests received.

func (*FakePBX) URI 

func (pbx *FakePBX) URI(extension string) string

URI returns a SIP URI for an extension: "sip:1002@127.0.0.1:PORT"

func (*FakePBX) WaitForAck 

func (pbx *FakePBX) WaitForAck(n int, timeout time.Duration) bool

WaitForAck blocks until at least n ACKs are received or timeout elapses.

func (*FakePBX) WaitForBye 

func (pbx *FakePBX) WaitForBye(n int, timeout time.Duration) bool

WaitForBye blocks until at least n BYEs are received or timeout elapses.

func (*FakePBX) WaitForCancel 

func (pbx *FakePBX) WaitForCancel(n int, timeout time.Duration) bool

WaitForCancel blocks until at least n CANCELs are received or timeout elapses.

func (*FakePBX) WaitForInvite 

func (pbx *FakePBX) WaitForInvite(n int, timeout time.Duration) bool

WaitForInvite blocks until at least n INVITEs are received or timeout elapses.

func (*FakePBX) WaitForRegister 

func (pbx *FakePBX) WaitForRegister(n int, timeout time.Duration) bool

WaitForRegister blocks until at least n REGISTERs are received or timeout elapses.

type Info 

type Info struct {
	// contains filtered or unexported fields
}

Info is the handle passed to OnInfo handlers.

func (*Info) Accept 

func (i *Info) Accept()

Accept sends 200 OK.

func (*Info) Body 

func (i *Info) Body() []byte

Body returns the INFO body as raw bytes.

func (*Info) Reject 

func (i *Info) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Info) Request 

func (i *Info) Request() *sip.Request

Request returns the original SIP INFO request.

type Invite 

type Invite struct {
	// contains filtered or unexported fields
}

Invite is the handle passed to OnInvite handlers. It controls each step of call setup.

func (*Invite) Answer 

func (inv *Invite) Answer(sdp []byte) *ActiveCall

Answer sends a 200 OK with SDP and returns an ActiveCall handle. Must be called at most once per Invite.

func (*Invite) AnswerWithCode 

func (inv *Invite) AnswerWithCode(code int, sdp []byte) *ActiveCall

AnswerWithCode sends a 2xx response with SDP. For non-200 success codes.

func (*Invite) EarlyMedia 

func (inv *Invite) EarlyMedia(sdp []byte)

EarlyMedia sends 183 Session Progress with SDP body.

func (*Invite) From 

func (inv *Invite) From() string

From returns the From URI of the INVITE.

func (*Invite) Reject 

func (inv *Invite) Reject(code int, reason string)

Reject sends a non-2xx final response (e.g. 486, 503, 603).

func (*Invite) Request 

func (inv *Invite) Request() *sip.Request

Request returns the original SIP INVITE request.

func (*Invite) Respond 

func (inv *Invite) Respond(code int, reason string, hdrs ...sip.Header)

Respond sends a SIP response with the given status code, reason, and optional headers. For provisional responses (1xx), this can be called multiple times. For final responses (>=200), this is guarded by sync.Once — only the first final response (via Respond, Answer, or Reject) takes effect.

func (*Invite) Ringing 

func (inv *Invite) Ringing()

Ringing sends 180 Ringing.

func (*Invite) SDP 

func (inv *Invite) SDP() []byte

SDP returns the SDP body from the INVITE, or nil.

func (*Invite) To 

func (inv *Invite) To() string

To returns the To URI of the INVITE.

func (*Invite) Trying 

func (inv *Invite) Trying()

Trying sends 100 Trying.

func (*Invite) WaitForCancel 

func (inv *Invite) WaitForCancel(timeout time.Duration) bool

WaitForCancel blocks until a CANCEL is received or timeout elapses. Returns true if CANCEL arrived.

type Message 

type Message struct {
	// contains filtered or unexported fields
}

Message is the handle passed to OnMessage handlers.

func (*Message) Accept 

func (m *Message) Accept()

Accept sends 200 OK.

func (*Message) Body 

func (m *Message) Body() []byte

Body returns the message body as raw bytes.

func (*Message) Reject 

func (m *Message) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Message) Request 

func (m *Message) Request() *sip.Request

Request returns the original SIP MESSAGE request.

type Option 

type Option func(*config)

Option configures FakePBX.

func WithAuth 

func WithAuth(username, password string) Option

WithAuth sets digest auth credentials the PBX expects. If not set, REGISTER is accepted unconditionally.

func WithTransport 

func WithTransport(transport string) Option

WithTransport sets the SIP transport. Default: "udp".

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header. Default: "FakePBX/test".

type Options 

type Options struct {
	// contains filtered or unexported fields
}

Options is the handle passed to OnOptions handlers.

func (*Options) Accept 

func (o *Options) Accept()

Accept sends 200 OK.

func (*Options) Reject 

func (o *Options) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Options) Request 

func (o *Options) Request() *sip.Request

Request returns the original SIP OPTIONS request.

type RecordedRequest 

type RecordedRequest struct {
	Request   *sip.Request
	Timestamp time.Time
}

RecordedRequest holds a captured SIP request with timestamp.

type Refer 

type Refer struct {
	// contains filtered or unexported fields
}

Refer is the handle passed to OnRefer handlers.

func (*Refer) Accept 

func (r *Refer) Accept()

Accept sends 202 Accepted.

func (*Refer) ReferTo 

func (r *Refer) ReferTo() string

ReferTo returns the value of the Refer-To header. Angle brackets are stripped if present.

func (*Refer) Reject 

func (r *Refer) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Refer) Request 

func (r *Refer) Request() *sip.Request

Request returns the original SIP REFER request.

type Register 

type Register struct {
	// contains filtered or unexported fields
}

Register is the handle passed to OnRegister handlers.

func (*Register) Accept 

func (r *Register) Accept()

Accept sends 200 OK.

func (*Register) Challenge 

func (r *Register) Challenge(realm, nonce string)

Challenge sends 401 Unauthorized with a WWW-Authenticate header.

func (*Register) Reject 

func (r *Register) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Register) Request 

func (r *Register) Request() *sip.Request

Request returns the original SIP REGISTER request.

type Subscribe 

type Subscribe struct {
	// contains filtered or unexported fields
}

Subscribe is the handle passed to OnSubscribe handlers.

func (*Subscribe) Accept 

func (s *Subscribe) Accept()

Accept sends 200 OK.

func (*Subscribe) Event 

func (s *Subscribe) Event() string

Event returns the value of the Event header.

func (*Subscribe) Reject 

func (s *Subscribe) Reject(code int, reason string)

Reject sends a non-2xx final response.

func (*Subscribe) Request 

func (s *Subscribe) Request() *sip.Request

Request returns the original SIP SUBSCRIBE request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.