[anna.git] / example / diameter / launcher / resources / HELP.md

# OVERVIEW

The ADML (*ANNA Diameter MultiHost Launcher*) process is a multi-host node with client and server capabilities as well as balancer (proxy) features. It could be used as diameter server (i.e. to simulate PCRF nodes, OCS systems, etc.), as diameter client (GGSNs, DPIs, etc.), and balancer systems to provide failover to external round-robin launchers. Also, auxiliary encoder/decoder/loader function could be deployed to reinterpret certain external flow and send it to another process.

The *ANNA::diameter_comm* built-in module provides a great set of characteristics as multiple connections on both server and client side, definition for multiple-server entities (and not only two as standard establish as minimum), separate statistics analyzer per each resource, automatic CER/CEA and DWR/DWA generation, expiration control and many more features.

The ADML process can easily configure a many origin-host nodes as needed, which will have own endpoints. You should avoid loop configurations (client and server for that client) because automatic forwarding, is implemented and this would get in a never ending cycle when a request is sent.

Process traces are dump on \"launcher.trace\" and could have any trace level (POSIX levels), usually 'debug' or 'warning'. See ANNA documentation for more details.

As any other ANNA process, context dump could be retrieved sending SIGUSR1 signal:
   kill -10 <pid>
    or
   kill -s SIGUSR1 <pid>
    and then
   vi /var/tmp/anna.context.<pid>

A complete xml report will show all the context information (counters, alarms, statistics, handlers, diameter stacks, etc.), and a powerful log module could dump all the events processed and flow information. Statistics could be analized at context dump and optionally written to disk as sample files (useful for graphs and spreadsheet reports) with all the measurements.

Also SIGUSR2 is handled for management purposes. We will talk later about this.


COMMAND LINE
============

Start the launcher process without arguments in order to see all the startup configuration posibilities, many of which could be modified on the air through the management interface (we will talk later about this great feature). There is only one mandatory parameter which is the services definition: --services <services xml file>. You must follow the dtd schema to build a valid services xml file. Some basic examples are:

Client configuration:

> <services>
>   <!-- Stacks -->
>   <stack id=\"0\" dictionary=\"dictionary.xml\"/>
>
>   <!-- Nodes -->
>   <node originHost=\"ADML-client\" applicationId=\"0\" entity=\"localhost:3868\"/>
> </services>

Server configuration:

> <services>
>   <!-- Stacks -->
>   <stack id=\"0\" dictionary=\"dictionary.xml\"/>
>
>   <!-- Nodes -->
>   <node originHost=\"ADML-server\" applicationId=\"0\" diameterServer=\"localhost:3868\"/>
> </services>

If you act as a proxy or a translation agent, you need to combine both former setups, and probably will need to program the answers to be replied through the operations interface. To balance the traffic at your client side you shall use '--balance' and '--sessionBasedModelsClientSocketSelection' arguments in order to define the balancing behaviour. To make hybrid setups you only must mix the nodes:

Client and server configuration:

> <services>
>   <!-- Stacks -->
>   <stack id=\"16777236\" dictionary=\"dictionary_Rx.xml\"/>
>   <stack id=\"16777238\" dictionary=\"dictionary_Gx.xml\"/>
>   <stack id=\"0\" dictionary=\"dictionary_base.xml\"/>
>
>   <!-- Nodes -->
>   <node originHost=\"ADML-Rx-client\" applicationId=\"16777236\" entity=\"localhost:3868\" cer=\"cer_Rx.xml\"/>
>   <node originHost=\"ADML-Gx-client\" applicationId=\"16777238\" entity=\"localhost:3868\" cer=\"cer_Gx.xml\"/>
> </services>

The process builds automatically CER and DWR messages as a client, but you could specify your own as shown in the hybrid former example. Note that the base protocol stack must be registered because the configuration corresponds to a multistack process which change the stack using the application-id processed (0 in the case of base protocol messages: CER, CEA, DWR, DWA, DPR, DPA).

DYNAMIC OPERATIONS
==================

ADML supports several operations which could be recognized via SIGUSR2 caugh or HTTP interface:

## SIGUSR2 caugh

Requires the creation of the task(s) file which will be read at signal event:

>    echo \"<operation>\" > "; result += getSignalUSR2InputFile();
>     then
>    kill -12 <pid>
>     or
>    kill -s SIGUSR2 <pid>
>     and then see the results:
>    cat "; result += getSignalUSR2OutputFile();

   (this file is ended with EOF final line, useful managing huge batch files to ensure the job completion)

You could place more than one line (task) in the input file. Output reports will be appended in that case over the output file. Take into account that all the content of the task file will be executed sinchronously by the process. If you are planning traffic load, better use the asynchronous http interface.

An operation is specified by mean a string containing the operation name and needed arguments separated by pipes. These are the available commands:

### Node management

**node[|<name>]**

Selects a context working node by mean a registered name (origin-host).
All the subsequent operations will be forced to work with this node, which makes possible some rare scenarios like sending unexpected messages on remote peers. This is also useful for some operations in order to restrict the scope of action (statistics, communication visibility, etc.).

Empty parameter will show the current configuration.

**node-auto**

Returns to the default behaviour (smart node selection).
Depending on the operation, this could imply a global action scope, affecting to all the registered hosts.
This should be the normal configuration. Take into account that if you fix the working node, this could affect to things like test programming: communication resources will override those which would be inferred from programmed messages Origin-Host avps.

### Parsing operations

**code|<source_file>|<target_file>**

Encodes source file (pathfile) into target file (pathfile).

**decode|<source_file>|<target_file>**

Decodes source file (pathfile) into target file (pathfile).

**loadxml|<source_file>**

Reinterpret xml source file (pathfile).

### Hot changes

**services[|<source file>]**

Adds and starts the services specified in the xml file provided. If missing, the file 'services.xml' will be used. This is used to load new nodes once the ADML is started, regardless if command line '--services' parameter was used or not. Those services which are not correctly loaded will be ignored to keep the process alive.
If you need to load services as deltas, you must firstly load the diameter base dictionary with stack id 0, because all the nodes will use this dictionary to encode/decode base protocol messages managed by the communication engine.

**diameterServerSessions|<integer>**

Updates the maximum number of accepted connections to diameter server socket.

**change-dir[|directory]**

Changes the execution point which could be fine to ease some file system interaction tasks. Be care about some requirements (for example if you have a user defined counters directory as relative path this must exists from the new execution directory). If nothing provided, initial working directory will be restored.

### Client sessions visibility

<action: **hide**, **show**, **hidden**, **shown**>|<address>:<port>|<socket>

*Actions*: hide, show (update state) and hidden, shown (query state).
Acts over a client session for messages delivery (except CER/A, DWR/A, DPR/A).
If missing server (first parameter) all applications sockets will be affected.
If missing socket (second parameter) for specific server, all its sockets will be affected.

All application client sessions are shown on startup, but standard delivery only use primary server ones except if fails. Balance configuration use all the allowed sockets. You could also use command line 'sessionBasedModelsClientSocketSelection' to force traffic flow over certain client sessions, but for this, hide/show feature seems easier.

### Snapshots

**collect**

Reset statistics and counters to start a new test stage of performance measurement. Context data can be written at '/var/tmp/anna.context.<pid>' by mean 'kill -10 <pid>' or sending operation 'context|[target file]'. This operation applies over all the registered host nodes except if one specific working node has been set.

**context[|<target file>]**

Application context could also be written by mean this operation (not only through SIGUSR1). If optional path file is missing, default '/var/tmp/anna.context.<pid>' will be used.

**forceCountersRecord**

Forces dump to file the current counters of the process.

**log-statistics-samples|<list>**

Log statistics samples for the provided comma-separated concept id list, over './sample.<concept id>.csv' files. For example: "1,2" will log concepts 1 and 2. Reserved words "all"/"none" activates/deactivates all registered statistics concept identifiers. That ids are shown at context dump.

**show-oam**

Dumps current counters of the process. This is also done at process context dump.

**show-stats**

Dumps statistics of the process. This is also done at process context dump.

### Flow operations

**sendxml2e|<source_file>**

Sends xml source file (pathfile) through configured entity.

**sendxml2c|<source_file>**

Sends xml source file (pathfile) to client.

**answerxml2e[|source_file]**

Answer xml source file (pathfile) for incoming request with same code from entity.
The answer is stored in a FIFO queue for a specific message code, then there are as many queues as different message codes have been programmed.

**answerxml2c[|source_file]**

Answer xml source file (pathfile) for incoming request with same code from client. The answer is stored in a FIFO queue for a specific message code, then there are as many queues as different message codes have been programmed.

**answerxml<2e/2c>**

List programmed answers (to entity/client) if no parameter provided.

**answerxml<2e/2c>|dump**

Write programmed answers (to entity/client) to file 'programmed_answer.<message code>.<sequence>', where 'sequence' is the order of the answer in each FIFO code-queue of programmed answers.

**answerxml<2e/2c>|clear**

Clear programmed answers (to entity/client).

**answerxml<2e/2c>|exhaust**

Disable the corresponding queue rotation, which is the default behaviour.

**answerxml<2e/2c>|rotate**

Enable the corresponding queue rotation, useful in performance tests. Rotation consists in add again to the queue, each element retrieved for answering.

Send operations are available using hexadecimal content (hex formatted files) which also allow to test
special scenarios (protocol errors):

**sendhex2e|<source_file>**

Sends hex source file (pathfile) through configured entity.

**sendhex2c|<source_file>**

Sends hex source file (pathfile) to client.

Answer programming in hexadecimal is not really neccessary (you could use send primitives) and also is intended to be used with decoded messages in order to replace things like hop by hop, end to end, subscriber id, session id, etc. Anyway you could use 'decode' operation and then program the xml created.

If a request is received, answer map (built with 'answerxml<2e/2c>' operations) will be checked to find a corresponding programmed answer to be replied(*). If no ocurrence is found, or answer message was received, the message is forwarded to the other side (entity or client), or nothing but trace when no peer at that side is configured. Answer to client have sense when diameter server socket is configured, answer to entity have sense when entity does.

In the most complete situation (process with both client and server side) there are internally two maps with N FIFO queues, one for each different message code within programmed answers. One map is for answers towards the client, and the other is to react entity requests. Then in each one we could program different answers corresponding to different request codes received.

(*) sequence values (hop-by-hop and end-to-end), Session-Id and Subscription-Id avps, are mirrored to the peer which sent the request. If user wants to test a specific answer without changing it, use 'sendxml<2e/2c>/sendhex<2e/2c>' operations better than programming.

Balance ('--balance' command line parameter) could be used to forward server socket receptions through entity servers by mean a round-robin algorithm. Both diameter server socket and entity targets should have been configured, that is to say: launcher acts as client and server. If no balance is used, an standard delivery is performed: first primary entity server, secondary when fails, etc.

### Processing types (log tags)

Used as log file extensions (when '--splitLog' is provided on command line) and context preffixes on log
 details when unique log file is dumped:

| MULTIPLEXOR IDENTIFIER | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| [sent2e/send2eError]   | Send to entity (success/error)                               |
| [sent2c/send2cError]   | Send to client (success/error)                               |
| [fwd2e/fwd2eError]     | Forward to entity a reception from client (success/error)    |
| [fwd2c/fwd2cError]     | Forward to client a reception from entity (success/error)    |
| [recvfc]               | Reception from client                                        |
| [recvfe]               | Reception from entity                                        |
| [req2c-expired]        | A request sent to client has been expired                    |
| [req2e-expired]        | A request sent to entity has been expired                    |
| [recvfc-ans-unknown]   | Reception from client of an unknown answer (probably former [req2c-expired] has been logged) |
| [recvfe-ans-unknown]   | Reception from entity of an unknown answer (probably former [req2e-expired] has been logged) |
| [retry]                | Request retransmission                                       |

### Burst test

In order to simplify user experience, burst category operations are only allowed in single host node
 configuration. Indeed, you could send messages with unmatched Origin-Host, and no warning is shown.
All the operations are performed through the unique host: if you need to use more interfaces, you may
 launch different ADML instances. Is nonsense to allow burst in a multi-host configured ADML, because
 this feature is not able to coordinate the messages.

**burst|<action>[|parameter]**

Used for performance testing, we first program diameter requests messages in order to launch them from client side to the configured diameter entity. We could start the burst with an initial load (non-asynchronous sending), after this, a new request will be sent per answer received or expired context. There are 10 actions: clear, load, start, push, pop, stop, repeat, send, goto and look.

| OPERATION                    | DESCRIPTION                                                  |
| ---------------------------- | ------------------------------------------------------------ |
| burst\|clear                 | Clears all loaded burst messages.                            |
| burst\|load\|<source_file>   | Loads the next diameter message into launcher burst.         |
| burst\|start\|<initial load> | Starts (or restarts if already in progress) the message sending with a certain initial load. |
| burst\|push\|<load amount>   | Sends specific non-aynchronous load.                         |
| burst\|pop\|<release amount> | Skip send burst messages in order to reduce over-the-air requests. Popping all OTA requests implies burst stop because no more answer will arrive to the process. Burst output file (--burstLog command line parameter) shows popped messages with crosses (x). Each cross represents one received answer for which no new request is sent. |
| burst\|stop\|                | Stops the burst cycle. You can resume pushing 1 load amount. |
| burst\|repeat[\|[yes]\|no]   | Restarts the burst launch when finish. If initial load or push load amount is greater than burst list size, they will be limited when the list is processed except when repeat mode is enabled. |
| burst\|send\|<amount>        | Sends messages from burst list. The main difference with start/push operations is that burst won't be awaken. Externally we could control sending time (no request will be sent for answers). |
| burst\|goto\|<order>         | Updates current burst pointer position.                      |
| burst\|look[\|order]         | Show programmed burst message for order provided, current when missing. |

### Advanced testing (FSM, finite state machine)

Burst mode only allows single interface interaction. For multiple interface (origin-host) coordination, you could use the advanced test cases programming:

   **test|<id>|<command>[|parameters]**

Adds a new step to the test case with provided identifier. If provided identifier is not registered yet, a new test case will be created with that value and the step will be added as the first. For a specific 'id', the steps are stored in order as they are programmed. Check possible runtime exceptions when adding a new step because those which fail, will be ignored/skipped during test case programming giving an incomplete sequence invalid for the testing purpose.

<id>: integer number, normally monotonically increased for each test case. Some external script/procedure shall clone a test case template in order to build a collection of independent and coherent test cases (normally same type) with different context values (Session-Id, Subscriber-Id, etc.).

<command>: commands to be executed for the test id provided. Each command programmed constitutes a test case 'step', numbered from 1 to N, with an exception for 'description' which is used to describe the test case:



> **description|<description>**
>
> Sets a test case description. Test cases by default are constructed with description 'Testcase_<id>'.
>
> **ip-limit[|amount]**
>
> In-progress limit of test cases controlled from this test. No new test cases will be launched over this value (test manager tick work will be ignored). Zero-value is equivalent to stop the clock tick, -1 is used to specify 'no limit' which is the default. For missing amount, value of 1 is applied.
>
> **timeout|<msecs>**
>
> Sets an asynchronous timer to restrict the maximum timeout until last test step. Normally, this command is invoked in the first step, anyway it measures the time from the execution point whatever it is. The expiration will abort the test if still running. One or more timeouts could be programmed (not usual), but the more restrict will apply.
> It is highly recommended to program a initial timeout step, or the test case could be eternally in-progress.
>
> **sendxml2e|<source_file>[|<step number>]**
> Sends xml source file (pathfile) to entity (it would be a 'forward' event if it came through local server endpoint).
> Take into account that the xml message is encoded just on call. The xml file is not longer needed neither interpreted in case of modification, after calling this command. The step number should be provided for answers to indicate the 'wait for request' corresponding step. If you miss this reference, the sequence information (hop-by-hop, end-to-end) will be sent as they are in the answer xml message (realize the difficulty of predicting these information). Be sure to refer to a 'wait for request' step. Conditions like 'regexp' (as we will see later) are not verified.
> In the case of requests, the step number is used to force the copy of Session-Id value from the referred step.
>
> **sendxml2c|<source_file>[|<step number>]**
> Sends xml source file (pathfile) to client (it would be a 'forward' event if it came through remote server endpoint). Same commented for 'sendxml2e' regarding the step number.
>
> **delay|<msecs>**
>
> Blocking step until the time lapse expires. Useful to give some cadence control and time schedule for a specific case. A value of 0 could be used as a dummy step.
>
> **sh-command|<script>**
>
> External execution for script/executable via shell through a dedicated thread, providing the command and parameters. You could use dynamic variables ##<tag> to have more flexibility:
> Test pool cycle id: ##cycleid##
> Test case id: ##testcaseid##
> Test step id: ##teststepid##
>
> For example, your command could be something like this:
>
> > insert_sql_##testcaseid##.sh -db dbname --verbose > /tmp/cycle-##cycleid##.testcase-##testcaseid##.teststep-##teststepid##.out
>
>
>
> Try to redirect stdout and stderr to avoid ADML output contamination with the possible outputs from the scripts. You could also put your job in background although sh-command will return 0-value immediately.
>
> **wait<fe/fc>-hex|<source_file>[|strict]**
> Wait condition, from entity (waitfe-hex) or client (waitfc-hex) to match the hexadecimal representation for received messages against source file (hex format). Fix mode must be enabled to avoid unexpected matching behaviour. Specify 'strict' to use the hex content 'as is'.
> If not, the hex content will be understood as whole message and then, borders will be added (^<content>$) and sequence information bypassed even for diameter answers.
>
> **wait<fe/fc>-xml|<source_file>[|strict]**
> Wait condition from entity (waitfe-xml) or client (waitfc-xml) to match the serialized xml content for received messages against source file (xml representation). Fix mode must be enabled to avoid unexpected matching behaviour. If you need a strict matching you must add parameter 'strict', if not, regexp is built ignoring sequence information (hop-by-hop-id=\"[0-9]+\" end-to-end-id=\"[0-9]+\") and Origin-State-Id value.
>
> **wait<fe/fc>|<condition>**
>
> Blocking step until condition is fulfilled. The message could received from entity (waitfe) or from client (waitfc). CPU cost is lower than former 'wait<fe/fc>-<xml|hex>' variants.
>
> > <condition>:
> >
> > Optional parameters which must be fulfilled to continue through the next step. Any received message over diameter interfaces will be evaluated against the corresponding test case starting from the current step until the first one whose condition is fulfilled. If no condition is fulfilled the event will be classified as 'uncovered' (normally a test case bad configuration, or perhaps a real unexpected message).
> >
> > How to answer: a wait condition for a request will store the incoming message which fulfills that condition. This message is useful together with the peer connection source in a further send step configured with the corresponding response. You could also insert a delay between wait and send steps to be more realistic (processing time simulation in a specific ADML host node).
> > Always, a response send step will get the needed information from the most recent wait step finding in reverse order (note that some race conditions could happen if your condition is not specific enough).
> >
> > Condition format is: **[code]|[bitR]|[hopByHop]|[applicationId]|[sessionId]|[resultCode]|[msisdn]|[imsi]|[serviceContextId]**
> >
> > *code*: integer number
> > *bitR*: 1 (request), 0 (answer)
> > *hopByHop*: integer number or request send step reference: #<step number>
> >
> > Using the hash reference, you would indicate a specific wait condition for answers. The step number provided must correspond to any of the previous send commands (sendxml2e/sendxml2c) configured for a request.
> > This 'hop-by-hop' variant eases the wait condition for answers in the safest way.
> >
> > *applicationId*: integer number
> > *sessionId*: string
> > *resultCode*: integer number
> > *msisdn*: string
> > *imsi*: string
> > *serviceContextId*: string
> >
> > Take into account these rules, useful in general:
> >
> > - Be as much specific as possible defining conditions to avoid ambiguity sending messages out of context due to race conditions. Although you could program several times similar conditions, some risky practices will throw a warning trace (if you repeat the same condition within the same test case).
> > - Adding a ResultCode and/or HopByHop to the condition are only valid waiting answers.
> > - Requests hop-by-hop values must be different for all the test case requests.
> > RFC says that a hop by hop must be unique for a specific connection, something that could be difficult to manage if we have multiple available connections from client side endpoint (entity or local server), even if we would have only one connection but several host interfaces. It is enough to configure different hop-by-hop values within each test case, because on reception, the Session-Id is used to identify that test case.

####  Programming example:

*Basic Rx/Gx scenary: PCEF (Gx) - PCRF - AF (Rx)*

test|1|timeout|5000
test|1|sendxml2e|CCR-I.xml
test|1|waitfe|272|0|||SGx|2001
test|1|sendxml2e|AAR-flows.xml
test|1|waitfe|265|0|||SRx|2001
test|1|waitfe|258|1|||SGx
test|1|sendxml2e|RAA-install.xml|6
test|1|sendxml2e|CCR-T.xml
test|1|waitfe|272|0|H1||SGx|2001
test|1|waitfe|258|1|||SGx
test|1|sendxml2e|RAA-remove.xml|10



- Step 1: whole time requirement is 5 seconds
- Step 2: imagine this xml uses the Session-Id 'SGx'
- Step 3: waits the CCA for the CCR-I with Result-Code = DIAMETER_SUCCESS
- Step 4: imagine this xml uses the Session-Id 'SRx'
- Step 5: waits the AAA for the AAR-flows with Result-Code = DIAMETER_SUCCESS
- Step 6: waits the RAR (install policies) from the PCRF server
- Step 7: sends the response for the RAR
- Step 8: termination of the Gx session, imagine this xml puts hop-by-hop 'H1'
- Step 9: waits the CCA for the CCR-T with Result-Code = DIAMETER_SUCCESS and hop-by-hop 'H1'
- Step 10: waits the RAR (remove policies) from the PCRF server
- Step 11: sends the response for the RAR



**Notes**:

We added an additional condition in step 9: the hop-by-hop. When we program the corresponding source request (CCR-T), we configured the value 'H1' for the hop-by-hop. This is an 'application value' because the real hop-by-hop transported through the client connection is managed by the diameter stack. But when returned, the transaction pool resolve the original value. This feature is necessary to ease the implementation of certain diameter agents (proxies for example). In our case, we could format the hop-by-hop values within the request templates with total freedom to improve the programmed conditions.

In the case of 'waiting for requests' is not such easy. Indeed, steps 6 and 10 will write a warning because they are the same condition. We know that we are not going to have any problem because such events are blocking-protected regarding logic-dependent messages (CCR-T), and race condition is absolutely strange in this case.

You could speed up the test case moving forward steps like 3 & 5, understood as non-strict requirements to continue testing. Anyway, remember that test cases should be as real as possible, and that there are many ways to increase the load rate as we will see in next section (test cases execution).

Other simplifications: the steps 3, 5 and 9 can be replaced by

test|1|waitfe||0|#2
test|1|waitfe||0|#4
test|1|waitfe||0|#8

which means that hop-by-hop must be retrieved from steps 2, 4 and 8 respectively, and the expected message shall be an answer. Normally you will add other conditions, for example a DIAMETER_SUCCESS result (adding 2001 as Result-Code).

#### Test cases execution:

**test|ttps|<amount>**

Starts/resume the provided number of test ticks per second (ttps). The ADML starts with the event trigger system suspended, and this operation is neccessary to begin those cases which need this time event (internal triggering). Some other test cases could be started through external events (first test case event could be programmed to wait specific message), but is not usual this external mode and neither usual to mix triggering types. Normally, you will pause/stop new test launchs providing 0 as ttps value, and also you could dynamically modify the load rate updating that value. If a test case has N messages then 'ttps * N' will be the virtual number of messages managed per second when no bottleneck exists.

Provide 0 in order to stop the timer triggering.

The timer manager resolution currently harcoded allows a maximum  of 50 events per second. To reach greater rates ADML will join synchronously the needed number of new time-triggered test cases per a single event, writting a warning-level trace to advice about the risk of burst sendings and recommend launching multiple instances to achieve such load with a lower rate per instance.

**test|next[|<sync-amount>]**

Forces the execution of the next test case(s) without waiting for test manager tick.
Provide an integer value for 'sync-amount' to send a burst synchronous amount of the next programmed test cases (1 by default). This event works regardless the timer tick function, but it is normally used with the test manager tick stopped.

**test|ip-limit[|amount]**

In-progress limit of test cases established from global context. This value will be overwritten if used at test case level when the corresponding test step is executed.
Anyway, the meaning is the same in both contexts. But now, when the amount is missing, the limit and current amount of in-progress test cases will be shown.

**test|goto|<id>**

Updates current test pointer position. Take into account, that 'test|next' will execute the next test case, not the one pointed with *goto*.

**test|run|<id>**

Run the test case selected.

**test|look[|id]**

Show programmed test case for id provided, current 'in-process' test case when missing.
Test cases reports are not dumped on process context (too many information in general).
The report contains context information in every moment: this operation acts as a snapshot.

**test|state[|id]**

Get test case state for id provided, current 'in-process' test case when missing.

**test|interact|amount[|id]**

Makes interactive a specific test case id. The amount is the margin of execution steps to be done. Normally, we will execute 'test|interact|0[|<test case id>]', which means that the test case is selected to be interactive, but no step is executed. Then you have to interact with positive amounts (usually 1), executing the provided number of steps if they are ready and fulfill the needed conditions. The value of 0, implies no execution steps margin, which could be useful to 'freeze' a test in the middle of its execution.
You could also provide -1 to make it non-interactive resuming it from the current step.
By default, current test case id is selected for interaction.

**test|reset|<[soft]/hard>[|id]**

Reset the test case for id provided, all the tests when missing. It could be hard/soft:

- hard: you probably may need to stop the load rate before. This operation initializes all test cases regardless their states.
- soft: only for finished cases (those with 'Success' or 'Failed' states). It does not affect to test cases with 'InProgress' state.

**test|repeats|<amount>**

Restarts the whole programmed test list when finished the amount number of times (repeats forever if value -1 is provided). This is disabled by default (amount = 0): testing trigger system will enter suspended state until new ttps operation is received and a soft reset has been done before. Test cases state & data will be reset (when achieved again), but general statistics and counters will continue measuring until reset with 'collect' operation.

**test|auto-reset|<soft|hard>**

When cycling, current test cases can be soft or hard reset. If no timeout has been configured for the test case, hard reset could prevent stuck on the next cycle for those test cases still in progress.

**test|initialized**

Shows the number of initialized test cases. Zero-value means that everything was processed or not initiated yet.

**test|finished**

Shows the number of finished (successful or failed) test cases.

**test|clear**

Clears all the programmed test cases and stop testing (if in progress).

**test|junit**

Shows the junit report in the moment of execution.

**test|summary-counts**

Test manager counts report. Counts by state and prints total verdict.

**test|summary-states**

Test manager states report.

**test|summary**

Test manager general report (number of test cases, counts by state, global configuration, forced in-progress limitation, reports visibility, etc.). Be careful when you have reports enabled because the programmed test cases dumps could be heavy (anyway you could enable the dumps separately, for any of the possible states: Initialized, InProgress, Failed, Success).

**test|report|<initialized/in-progress/failed/success/[all]/none>[|[yes]|no]**

Enables/disables report generation for a certain test case state: initialized, in-progress, failed or success (also 'all' and 'none' reserved words could be used). This applies to report summary (former described operation) and automatic dumps during testing where only failed or successful states will appear: every time a test case is finished its xml representation will be dump on a file under the execution directory (or the one configured in process command-line 'tmDir') with the name: 'cycle-<cycle id>.testcase-<test case id>.xml'.

By default, all the states are disabled to avoid IO overload. In most of cases not all the tests are going to fail then you could enable only such failed dumps. Anyway you could set the reports visibility to fit your needs in a given situation

**test|report-hex[|[yes]|no]**

Reports could include the diameter messages in hexadecimal format. Disabled by default.

**test|dump-stdout[|[yes]|no]**

Test manager information is dumped into stdout.

### Dynamic procedure

**dynamic[|args]**

This launch an internal operation implemented in 'Procedure' class. Its default implementation does nothing, but you could create a dynamic library 'libanna_launcherDynamic.so' and replace the one in this project. One interesting application consists in the use of the diameter API and event operation to create a set of libraries as the testing framework.
To execute each test case, the ADML process would be executed with a specific library path. But the main use would be the stress programming to achieve a great amount of cloned (even mixed) tests without using the management operation interface by mean http or signals: a single call to 'dynamic' would be enough to start a cascade of internally implemented operations.
This operation accepts a generic string argument (piped or not, as you desire and depending on your procedure implementation).

This operation requires advanced programming and knowlegde of ANNA Diameter stack and testing framework, to take advantage of all the possibilities.


# HTTP Interface

Most of the operations described above can be used through the optional HTTP1.1 interface. You only have
 to define the http server at the command line with something like: '--httpServer localhost:8000'.
REST API specification.

**We will describe briefly the supported *GET* & *POST* operations, but you could extend the explanation from SIGUSR2 interface description above**.

Implemented status codes: *200* (ok), *400* (bad request) and *405* (method not allowed).

## GET

> curl -v --request GET localhost:8000<uri>

You could also expose the service as HTTP2 server through *nginx* working as reverse proxy (*anna-adml-http* image is built in this way although internally provides HTTP operations script only for 1.1). Then you could use HTTP2 clients like *nghttp*:

> nghttp -v -H ":method: GET" "<uri>"



### Snapshots

#### GET /show-oam

Retrieve oam xml report (will be *base64-encoded* at response).

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or base64-encoded xml report>"
}
```

#### GET /show-stats

Retrieve statistics xml report (will be *base64-encoded* at response).

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or base64-encoded xml report>"
}
```



## POST

> curl -v --request POST -H "Content-Type: application/json" localhost:8000<uri> -d@test.json

You could also expose the service as HTTP2 server through *nginx* working as reverse proxy (*anna-adml-http* image is built in this way although internally provides HTTP operations script only for 1.1). Then you could use HTTP2 clients like *nghttp*:

> nghttp -v -H ":method: POST" -d test.json "<uri>"



**Important note:** Anna Suite work natively with xml. Although REST API supports diameter messages (*diameterJson* fields) and services configuration (*servicesJson* fields) in *json* format, these messages are not validated directly with a *json schema*. Instead, the *json* object are converted to *xml*  at ADML and the resulting xml representations are validates against *dtd* schemas:

Schema for diameter messages: [here](../../../../include/anna/diameter/codec/message.dtd).

Schema for configuration services: [here](./services_examples/services.dtd).

There are lots of examples for *xml diameter messages and xml services* (normally deployed with *ADML* at `./xml_examples` and `./services_examples`), then you could transform them to the *json format* accepted by the REST API easily, for example using *xmltodict* python module:

```
#!/usr/bin/python3
import xmltodict
import json
import sys

try:
  file = sys.argv[1]
except:
  print("Usage: " + sys.argv[0] + " <diameter xml file>")
  sys.exit(1)

try:
  with open(file, 'r') as myfile:
    xml = myfile.read()
except:
  print("ERROR reading '" + file + "'")
  sys.exit(1)

# although default attribute prefix is '@', anyway we will
# force the value just in case xmltodict implementation
# changes. The anna::core::functions::json2xml helper,
# assumes this prefix in order to work properly.
my_dict=xmltodict.parse(xml, attr_prefix='@')
json_data=json.dumps(my_dict, indent=3, sort_keys=True)
print(json_data)
```

**Former script is packaged** together with REST API component tests under `./diameterJsonHelper/xml2json.py`.

Native example for *AA-Request* diameter message:

```
<message version="1" name="AA-Request" p-bit="yes" application-id="16777236" hop-by-hop-id="0" end-to-end-id="0">
   <avp name="Session-Id" data="test1;afNodeHostname.nodeHostRealm.com;1;8033450"/>
   <avp name="Auth-Application-Id" data="16777236"/>
   <avp name="Origin-Host" data="afHost.afRealm.com"/>
   <avp name="Origin-Realm" data="afRealm.com"/>
   <avp name="Destination-Realm" data="operatorRealm.com"/>
   <avp name="Destination-Host" data="ownHostId.operatorRealm.com"/>
   <avp name="AF-Application-Identifier" hex-data="313232"/>
   <avp name="Media-Component-Description">
      <avp name="Media-Component-Number" data="0"/>
      <avp name="AF-Application-Identifier" hex-data="313232"/>
      <avp name="Max-Requested-Bandwidth-UL" data="127"/>
      <avp name="Max-Requested-Bandwidth-DL" data="133"/>
      <avp name="Flow-Status" data="2" alias="ENABLED"/>
      <avp name="Reservation-Priority" data="0" alias="DEFAULT"/>
   </avp>
   <avp name="Service-Info-Status" data="0" alias="FINAL_SERVICE_INFORMATION"/>
   <avp name="Subscription-Id">
      <avp name="Subscription-Id-Type" data="0" alias="END_USER_E164"/>
      <avp name="Subscription-Id-Data" data="626037099"/>
   </avp>
   <avp name="Framed-IP-Address" hex-data="3139322e3136382e302e31"/>
   <avp name="Called-Station-Id" hex-data="5741502e4d4f564953544152"/>
</message>

```

Corresponding content in *json* format:

```
{
   "message": {
      "@application-id": "16777236",
      "@end-to-end-id": "0",
      "@hop-by-hop-id": "0",
      "@name": "AA-Request",
      "@p-bit": "yes",
      "@version": "1",
      "avp": [
         {
            "@data": "test1;afNodeHostname.nodeHostRealm.com;1;8033450",
            "@name": "Session-Id"
         },
         {
            "@data": "16777236",
            "@name": "Auth-Application-Id"
         },
         {
            "@data": "afHost.afRealm.com",
            "@name": "Origin-Host"
         },
         {
            "@data": "afRealm.com",
            "@name": "Origin-Realm"
         },
         {
            "@data": "operatorRealm.com",
            "@name": "Destination-Realm"
         },
         {
            "@data": "ownHostId.operatorRealm.com",
            "@name": "Destination-Host"
         },
         {
            "@hex-data": "313232",
            "@name": "AF-Application-Identifier"
         },
         {
            "@name": "Media-Component-Description",
            "avp": [
               {
                  "@data": "0",
                  "@name": "Media-Component-Number"
               },
               {
                  "@hex-data": "313232",
                  "@name": "AF-Application-Identifier"
               },
               {
                  "@data": "127",
                  "@name": "Max-Requested-Bandwidth-UL"
               },
               {
                  "@data": "133",
                  "@name": "Max-Requested-Bandwidth-DL"
               },
               {
                  "@alias": "ENABLED",
                  "@data": "2",
                  "@name": "Flow-Status"
               },
               {
                  "@alias": "DEFAULT",
                  "@data": "0",
                  "@name": "Reservation-Priority"
               }
            ]
         },
         {
            "@alias": "FINAL_SERVICE_INFORMATION",
            "@data": "0",
            "@name": "Service-Info-Status"
         },
         {
            "@name": "Subscription-Id",
            "avp": [
               {
                  "@alias": "END_USER_E164",
                  "@data": "0",
                  "@name": "Subscription-Id-Type"
               },
               {
                  "@data": "626037099",
                  "@name": "Subscription-Id-Data"
               }
            ]
         },
         {
            "@hex-data": "3139322e3136382e302e31",
            "@name": "Framed-IP-Address"
         },
         {
            "@hex-data": "5741502e4d4f564953544152",
            "@name": "Called-Station-Id"
         }
      ]
   }
}
```

Native example for a services configuration example:

```
<services>
  <!--
  Stacks

  * Monostack: you could select any id value, normally 0.
  * Multistack: use the application id for the id value.
                This eases codec engine selection for
                processed messages.
  -->
  <stack id="0" dictionary="dictionary.xml" fixMode="Always" ignoreFlagsOnValidation="yes"/>

  <!--
  Nodes

  * Client example:

  <node originHost="<origin host>" applicationId="<application id>"
        entity="<addr1:port1[,addr2:port2]...[,addrN:portN]>"
        cer="<cer xml file>" answersTimeout="300000" dumpLog="yes"/>

  * Server example:

  <node originHost="<origin host>" applicationId="<application id>"
        diameterServer="<addr:port>" diameterServerSessions="10"
        cea="<cea xml file>" answersTimeout="300000" dumpLog="yes"/>
  -->
  <node originHost="afHost.afRealm.com" applicationId="0" entity="localhost:3868"/>
  <node originHost="ownHostId.operatorRealm.com" applicationId="0"
        diameterServer="localhost:3868" diameterServerSessions="1"/>

</services>
```

And the converted *json* equivalent:

```
{
   "services": {
      "node": [
         {
            "@applicationId": "0",
            "@entity": "localhost:3868",
            "@originHost": "afHost.afRealm.com"
         },
         {
            "@applicationId": "0",
            "@diameterServer": "localhost:3868",
            "@diameterServerSessions": "1",
            "@originHost": "ownHostId.operatorRealm.com"
         }
      ],
      "stack": {
         "@dictionary": "dictionary.xml",
         "@fixMode": "Always",
         "@id": "0",
         "@ignoreFlagsOnValidation": "yes"
      }
   }
}
```



**Note that the '@' character is mandatory to indicate attribute keys, and it is necessary to complete the *"json to xml"* conversion successfully at ADML REST Server endpoint.**



### Node management

#### POST /node

Selects a context working node by mean a registered name (origin-host). If empty, current node information is retrieved.

**Request body**:

```
{
    "name":"[node name]"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or base64-encoded xml information>"
}
```

#### POST /node-auto

Smart node selection.

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### Parsing operations

#### POST /code

Encodes a diameter json into hexadecimal representation.

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or diameter hex>"
}
```

#### POST /decode

Decodes an hexadecimal string (no spaces, no colons, i.e.: `01000150c0...`), into diameter xml (*base64-encoded*).

**Request body**:

```
{
    "diameterHex":"<hex string>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or base64-encoded xml diameter message>"
}
```

#### POST /loadmsg

Reinterprets diameter json into xml (*base64-encoded*).

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<error description or base64-encoded xml diameter message>"
}
```

### Hot changes

#### POST /services

Referred files (*dictionaries, cer, cea, etc.*) shall be accesible for ADML and are not provided in this operation.

**Request body**:

```
{
    "servicesJson":<services json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /diameterServerSessions

Updates diameter server sessions to be accepted.

**Request body**:

```
{
    "sessions":<sessions (integer)>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /change-dir

Updates ADML working directory.

**Request body**:

```
{
    "directory":"<directory path or empty to restore initial working directory>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### Client sessions visibility

#### POST /visibility

**Request body**:

```
{
    "action":"<hide|show|hidden|shown>"
    [, "addressPort":"<address:port>"]
    [, "socket":<socket id (integer)>]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### Snapshots

#### POST /collect

Reset statistics and counters.

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /context

Dump ADML context at file path provided. If empty (or field missing), default path is selected. Context information is not retrieved in the response, so, file is related to ADML execution context.

**Request body**:

```
{
    ["targetFile":"[file path]"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /forceCountersRecord

Forces dump to file the current counters of the process.

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /log-statistics-samples

Set the statistics concepts to be logged. To know the concept indentifiers registered, get the ADML context information.

**Request body**:

```
{
    ["list":"<comma-separated list|[all]|none>"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### Flow operations

#### POST /sendmsg2e

Sends diameter json message **to**(2) the connected **entity**(e).

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /sendmsg2c

Sends diameter json message **to**(2) the connected **client**(c).

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /answermsg2e

Answers diameter json message **to**(2) the connected **entity**(e).

Mocking FIFO queue based in message code.

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

or

```
{
    "action":"[action: <[list]|dump|clear|exhaust|rotate>]"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response or base64-encoded output for 'list' action>"
}
```

#### POST /answermsg2c

Answers diameter json message **to**(2) the connected **client**(c).

Mocking FIFO queue based in message code.

**Request body**:

```
{
    "diameterJson":<diameter message json object>
}
```

or

```
{
    "action":"[action: <[list]|dump|clear|exhaust|rotate>]"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response or base64-encoded output for 'list' action>"
}
```

#### POST /sendhex2e

Sends diameter expressed in hexadecimal string (no spaces, no colons, i.e.: `01000150c0...`), **to**(2) the connected **entity**(e).

**Request body**:

```
{
    "diameterHex":"<hex string>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /sendhex2c

Sends diameter expressed in hexadecimal string (no spaces, no colons, i.e.: `01000150c0...`), **to**(2) the connected **client**(c).

**Request body**:

```
{
    "diameterHex":"<hex string>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### FSM testing

ADML implements a bulting *Finite State Machine* to plan testing flows with a great flexibility.

#### POST /testid-description

**Request body**:

```
{
    "description":"<description (string)>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-ip-limit

In-Progress limit is the maximum number of tests which can be executed in parallel.
This operation allows a specific test to set this global pool behaviour.

Zero-value is equivalent to stop the clock (no tests will be executed).

Value '-1' means 'no limit' (full parallel). Be careful with resources consumption.

**Request body**:

```
{
    "amount":[amount (integer, 1 by default: execution in sequence)]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-timeout

**Request body**:

```
{
    "msecs":<milliseconds (integer)>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-sendmsg2e

**Request body**:

```
{
    "diameterJson":<diameter message json object>
    [,"stepNumber":[amount (integer, -1 no step associated)]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-sendmsg2c

**Request body**:

```
{
    "diameterJson":<diameter message json object>
    [,"stepNumber":[amount (integer, -1 no step associated)]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-delay

**Request body**:

```
{
    "msecs":<milliseconds (integer)>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-sh-command

**Request body**:

```
{
    "script":"<script>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfe-hex

**Request body**:

```
{
    "hex":"<hex string>"
    [,"strict":"[<true|[false]>]"]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfc-hex

**Request body**:

```
{
    "hex":"<hex string>"
    [,"strict":"[<true|[false]>]"]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfe-msg

**Request body**:

```
{
    "diameterJson":<diameter message json object>
    [,"strict":"[<true|[false]>]"]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfc-msg

**Request body**:

```
{
    "diameterJson":<diameter message json object>
    [,"strict":"[<true|[false]>]"]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfe

**Request body**:

```
{
    "condition": {
      "code":"[(integer)]",
      "bitR":"[(1|0)]",
      "hopByHop":"[(integer)]",
      "applicationId":"[(integer)]",
      "sessionId":"[session id]",
      "resultCode":"[(integer)]",
      "msisdn":"[msisdn]",
      "imsi":"[imsi]",
      "serviceContextId":"[service context id]"
    }
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /testid-waitfc

**Request body**:

```
{
    "condition": {
      "code":"[(integer)]",
      "bitR":"[(1|0)]",
      "hopByHop":"[(integer)]",
      "applicationId":"[(integer)]",
      "sessionId":"[session id]",
      "resultCode":"[(integer)]",
      "msisdn":"[msisdn]",
      "imsi":"[imsi]",
      "serviceContextId":"[service context id]"
    }
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### FSM TESTING EXECUTION ACTIONS

#### POST /test-ttps

**Request body**:

```
{
    "amount":<amount (integer)>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-next

**Request body**:

```
{
    ["syncAmount":[amount (integer: 1 by default)]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-ip-limit

Global operation (also at test identifier level is accessible).

Zero-value is equivalent to stop the clock (no tests will be executed).

Value '-1' means 'no limit' (full parallel). Be careful with resources consumption.

Defaults to '-2' (no '-1' which is default for *testid-ip-limit* version), which wil show the current pool *ip-limit* and also the number of test cases which are *in progress*.

**Request body**:

```
{
    ["amount":[amount (integer, shows current ip-limit and in-progress test cases amount, by default (-2))]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-goto

**Request body**:

```
{
    "id":<test identifier>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-run

**Request body**:

```
{
    "id":<test identifier>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-look

**Request body**:

```
{
     ["id":[test identifier (integer: current by default (-1))]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<base64-encoded output>"
}
```

#### POST /test-state

**Request body**:

```
{
     ["id":[test identifier (integer: current by default (-1))]]
}
```

**Response body**:

```
{
    "result":"<true: if state is 'Success' or false>",
    "response":"<response>"
}
```

#### POST /test-interact

Makes interactive a specific test case id. The amount of 0, implies no execution steps margin, which could be useful to 'freeze' a test in the middle of its execution. Value -1 makes it non-interactive resuming it from the current step.

**Request body**:

```
{
     "amount":<amount (integer)>
     [,"id":[test identifier (integer: current by default (-1))]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-reset

**Request body**:

```
{
     ["type":"<[soft]|hard>"]
     [,"id":[test identifier (integer: apply to all the tests (-1))]]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-repeats

**Request body**:

```
{
     "amount":<amount (integer)>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-auto-reset

**Request body**:

```
{
     "type":"<soft|hard>"
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-initialized

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-finished

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-clear

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-junit

As it could be very large, it will be dumped on provided target directory, '*/tmp/junit.xml*' by default.

**Request body**:

```
{
    ["targetFile":"<file path>"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-summary-counts

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<base64-encoded output>"
}
```

#### POST /test-summary-states

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<base64-encoded output>"
}
```

#### POST /test-summary

**Request body**: none

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<base64-encoded output>"
}
```

#### POST /test-report

**Request body**:

```
{
    ["state":"[<initialized|in-progress|failed|success|[all]|none>]"]
    [,"action":"[<[enable]|disable>]"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-report-hex

**Request body**:

```
{
    ["action":"[<[enable]|disable>]"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

#### POST /test-dump_stdout

**Request body**:

```
{
    ["action":"[<[enable]|disable>]"]
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```

### DYNAMIC PROCEDURE

Used for system test. Arguments are determined by the way in a specific dynamic library is designed/documented.

#### POST /dynamic

**Request body**:

```
{
    "dynamic": <diameter arguments json object>
}
```

**Response body**:

```
{
    "result":"<true or false>",
    "response":"<response>"
}
```