Values files: one scenario, many users

A scenario describes one call. Real tests need many calls that are not the same: 500 phones that each register with their own user name and password, calls from many different numbers, a sweep over a range of ports. Writing one scenario for every user does not scale. A values file solves this: the scenario is written once with placeholders, [field0], [field1] ..., and the values file is a table with one line for every call. Each new call takes the next line and puts its values in place of the placeholders.

How it works

1. The scenario uses [field0] where the first value goes, [field1] for the second, and so on. The keywords can be anywhere in a message the program sends: the request line, any header, the body, and inside the authentication keyword.
2. The values file has one line for every call. The values on a line are separated with ‘;’: the first is [field0], the second [field1] ...
3. Load it with File/Load Values (or -fv on the command line) and press Run. Every new call takes the next line. When the last line is used the program starts again at the first line, unless Options/Use Each Values Row Once is on (see below).

---------->
REGISTER sip:[remote_ip] SIP/2.0
From: <sip:[field0]@[remote_ip]>;tag=...
To: <sip:[field0]@[remote_ip]>
...
Proxy-Authorization: [authentication
  username=[field1]; password=[field2];]

//[field0];[field1];[field2]
107;user107;pass107
108;user108;pass108
109;user109;pass109

The scenario (left, from scenarios/Reg_series_client.txt) and its values file (right, values/Reg_series_values.txt)

A call takes its line when it first needs a value and keeps it to the end: the INVITE, the ACK and the BYE of one call always carry the same values, even when many calls run at the same time. A call that is a whole scenario run (with New Dialog entries, several dialogs) uses one line for all its dialogs.

Step by step: register many users

The sample files register a list of users against a registrar or a proxy that asks for authentication.

1. Load the scenario: File/Load Scenario, scenarios/Reg_series_client.txt.
2. Load the values: File/Load Values, values/Reg_series_values.txt. Edit it first so that it has your users and passwords, one user per line.
3. Turn on Options/Use Each Values Row Once: every user registers once, and the run ends after the last line. Total Calls can stay 0.
4. Set Calls/sec (for example 10) and Max Concurrent (for example 50), then press Run. The progress screen counts the REGISTERs and the 200 OKs; one 200 per line means every user is registered.

The same from the command line:

SIPInspDlx -lip 10.0.0.5 -rip 10.0.0.1 -fs scenarios/Reg_series_client.txt \
           -fv values/Reg_series_values.txt -fvo -cps 10 -mc 50

Writing a values file

Column names. With named columns a scenario says what it means: [field:user] instead of [field0]. The numbers keep working, and names ignore case. A name that is not a column gives an empty value; when the values file is loaded and before every run the program checks the names of the scenario against the columns, and the CLI prints a warning such as the scenario uses [field:pasword], but the values file has no column pasword (its columns: number, user, password).

CSV files. A values file whose name ends with .csv is read the way spreadsheets save it: values separated with commas, the first line names the columns, and a value in double quotes may have commas, line breaks and "" for a quote. Lines that start with # are comments. A .csv file without a first line of names can have a #columns: line instead. In an XML values file the root element names the columns: <values columns="user;password">.

number,user,password,display name
2001,alice,"se,cret","Smith, Alice"
2002,bob,pw2,Bob

From: "[field:display name]" <sip:[field:number]@[remote_ip]>;tag=[call_number]
Proxy-Authorization: [authentication username=[field:user]; password=[field:password];]

Values that span several lines or contain XML are easier to write in an XML values file. Each <rowValues> is a line, each <value> a column; CDATA keeps the text exactly as written:

<values>
  <rowValues>
    <value>John</value>
    <value>Doe</value>
    <value><![CDATA[;-)]]></value>
  </rowValues>
  <rowValues>
    <value>Smiley</value>
    <value>Face</value>
    <value><![CDATA[:-)]]></value>
  </rowValues>
</values>

Use each row once, or go around

By default the lines are used in turn, and after the last line the next call starts again at the first one. That is right for load tests: three accounts can make thousands of calls. Sometimes every line must be used exactly once: a list of real accounts to register or provision, numbers that must not be called twice, a list of devices to probe. Turn on Options/Use Each Values Row Once (-fvo on the command line): every line is given to one call, and after the last line the program makes no more calls. The run ends when those calls end, also when Total Calls is 0 (endless).

• The option is for the program as a client (it makes the calls). When the program is a server, an incoming call takes the next line; once every line is used the next calls get empty values, and SIPInspector.log says so.
• The option applies only when the scenario uses [fieldN] keywords; a scenario without them is not limited.
• Start on the progress screen begins again at the first line. The option is not kept after the program is closed, so a later test is never limited by surprise.

Counting values

A value written as start+step changes every time its line is used again, so one line can stand for thousands of different numbers. With the line below the first call uses [field0] = 5000000 and [field1] = 1, the second call 5000001 and 2, and so on:

5000000+1;1+1

Counting continues across rounds. With two lines, a;1+1 and b;1+1, the calls get a1, b1, a2, b2, a3 ... Example: values/Port_scan_values.txt has the single line 100;10024+1;: every call goes to the next port (10024, 10025, ...) of the address ending in .100, a port sweep with a one-line file.

Ready-made examples

The scenarios are in the folder scenarios, the values files in values.

When the values are not what you expect