fonoster / seet

SEET: Orchestrating multiple user-agents for complex SIP testing scenarios.

SIP End-to-End Testing

SEET is a suite for end-to-end testing of SIP deployments. We aim to add useful artifacts to help test and troubleshoot any SIP device or software. SEET is inspired in pysipp.

It lets you run complex scenarios involving multiple UASs and UACs. With SEET, you create your SIPp XML scenarios as usual and the suite creates the necesary User Agents and ensure the scenarios run in the correct sequence.

Scenario configuration

Property	Description	Required
name	The name of the scenario	Yes
description	The description of the scenario	No
target	System under test	No
transportMode	SIPp transport mode. Check here for possible values	Yes
domain	Needed for registration. Defaults to target	No
enabled	Enables scenario. Defauls to true	No
only	Exclude all other scenarios. Defauls to false	No
userAgents.[*].mode	User Agent mode. Possible values are uac and uas	Yes
userAgents.[*].port	Port to bind the User Agent	No
userAgents.[*].scenarioFile	Path to the SIPp XML scenario	Yes
userAgents.[*].authentication	Username and password for SIP authentication	No
userAgents.[*].sendRegister	Used for User Agent registration	No
userAgents.[*].sessionCount	Optional Session Count sent during registration. Defaults to 0	No
userAgents.[*].expires	Expiration in seconds use in for sendRegister. Defaults to 30	No
userAgents.[*].timeout	Maximum duration in seconds for the scenario	No
userAgents.[*].variables	Key-value array for SIPp XML scenario	No
userAgents.[*].maxIterations	Maximum number of iterations for the scenario (Experimental)	No
userAgents.[*].maxRate	Maximun rate of calls per second for the scenario (Experimental)	No
userAgents.[*].callLimit	Maximum simultaneous calls for the scenario (Experimental)	No

Example of scenario file

[
  {
    "name": "Simple SIP Message",
    "description": "UAC sends a simple MESSAGE to UAS and waits for an OK response",
    "target": "192.168.1.3",
    "transportMode": "u1",
    "domain": "sip.local",
    "userAgents": [
      {
        "mode": "uas",
        "scenarioFile": "scenarios/ims_uas.xml",
        "authentication": {
          "username": "1001",
          "secret": "1234"
        },
        "sendRegister": true,
        "expires": 30
      },
      {
        "mode": "uac",
        "scenarioFile": "scenarios/ims_uac.xml",
        "authentication": {
          "username": "1002",
          "secret": "1234"
        },
        "variables": [
          {
            "name": "requestURI",
            "value": "[email protected]"
          },
          {
            "name": "from",
            "value": "[email protected]"
          },
          {
            "name": "to",
            "value": "[email protected]"
          }
        ]
      }
    ],
    "enabled": true
  }
]

Available Versions

You can see all images available to pull from Docker Hub via the Tags page. Docker tag names that begin with a "change type" word, such as task, bug, or feature, are available for testing and may be removed at any time.

Installation

You can clone this repository and manually build it.

git clone https://github.com/fonoster/seet
cd seet
docker build -t fonoster/seet:%%VERSION%% .

Otherwise, you can pull this image from the docker index.

docker pull fonoster/seet:%%VERSION%%

Usage Example

The following is a basic example of using this image. Be sure to add the port of every User Agent Server. If you use an udp mode in your scenario (e.g. u1), you must also bind the port in docker with the corresponding notation.

docker run \
  -v $(pwd)/seet.json:/seet.json \
  -v $(pwd)/scenarios:/scenarios \
  -p 7060:7060/udp \
  -t fonoster/seet 

or with NodeJS

# Requires of sipp 3.6.0-r2 installed in the host
npm i -g @fonoster/seet
SCENARIOS=$(pwd)/seet_example.json seet

Environment Variables

Environment variables are used in the entry point script to render configuration templates. You can specify the values of these variables during docker run, docker-compose up, or in Kubernetes manifests in the env array.

• SCENARIOS - Changes the default path to the scenario file.

Exposed ports

None

Volumes

• /scenarios - Location for your SIPp XML files
• /seet.json - Default location for your scenarios file

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests to us.

Authors

• Pedro Sanders

See this project's list of contributors who participated.

License

Copyright (C) 2023 by Fonoster Inc. MIT License (see LICENSE for details).

seet's Issues

Test passing but seet throwing error

I'm running my test with an UAC and a UAS. The messages logs for both user agents generated by the test are as expected by the scenarios defined.
The output show that the scenario passed but also that the code thrown an error:

 SEET Test Plan / 1 scenario(s) found
    ✔ Basic Sipstone UAC


  1 passing (22s)

/usr/local/lib/node_modules/@fonoster/seet/node_modules/mocha/lib/runner.js:962
    throw err;
    ^

Error: done() called multiple times in test <SEET Test Plan / 1 scenario(s) found Basic Sipstone UAC> of file /usr/local/lib/node_modules/@fonoster/seet/dist/src/seet.js; in addition, done() received error: Error: timeout
    at Timeout._onTimeout (/usr/local/lib/node_modules/@fonoster/seet/dist/src/agent.js:71:18)
    at listOnTimeout (node:internal/timers:559:17)
    at processTimers (node:internal/timers:502:7)
    at createMultipleDoneError (/usr/local/lib/node_modules/@fonoster/seet/node_modules/mocha/lib/errors.js:428:13)
    at multiple (/usr/local/lib/node_modules/@fonoster/seet/node_modules/mocha/lib/runnable.js:290:24)
    at done (/usr/local/lib/node_modules/@fonoster/seet/node_modules/mocha/lib/runnable.js:301:14)
    at /usr/local/lib/node_modules/@fonoster/seet/node_modules/mocha/lib/runnable.js:396:16
    at Timeout._onTimeout (/usr/local/lib/node_modules/@fonoster/seet/dist/src/agent.js:71:13)
    at listOnTimeout (node:internal/timers:559:17)
    at processTimers (node:internal/timers:502:7) {
  code: 'ERR_MOCHA_MULTIPLE_DONE',
  valueType: 'object',
  value: Error: timeout
      at Timeout._onTimeout (/usr/local/lib/node_modules/@fonoster/seet/dist/src/agent.js:71:18)
      at listOnTimeout (node:internal/timers:559:17)
      at processTimers (node:internal/timers:502:7)
}

What does this error mean? How can I debug this if there are no error.log files generated?