# Asterisk Project : Test Configuration

Added by mjordan , edited by jbigelow on May 14, 2013

Every test has a test-config.yaml file that serves four purposes:

- It describes and documents the test
- It determines what necessary attributes an installation of Asterisk must have in order to run the test
- It determines what software must exist on a test system to run the test
- It configures attributes of the test

Some modules are configured via a test's test-config.yaml file. As those modules determine their own configuration, those configuration options are documented elsewhere.

## Specification

Keyword | Description | Required
--- | --- | ---
test-info | Section that describes basic information about the test | Yes
properties | Contains properties that define how the test executes | Yes
test-modules | Modules to load for tests that use the Test Suite's pluggable framework | No

If using the Test Suite's pluggable framework, the test-modules block is required.

### test-info

Keyword | Description | Required
--- | --- | ---
summary | A summary of what the test does | Yes
description | A detailed description of what functionality is covered by the test | Yes
skip | If true, skip execution of this test | No
issues | A sequence of key/value pairs specifying issues in an issue tracker related to this test | No

#### issues

Keyword | Description | Required
--- | --- | ---
mantis | A mantis issue identifier | No
jira | A JIRA issue identifier | No

### properties

Keyword | Description | Required
--- | --- | ---
minversion | The minimum version of Asterisk necessary to run the test | Yes
maxversion | The maximum version of Asterisk that this test can exeucte under | No
features | A sequence of feature specifies that the version of Asterisk under test must support. | No
dependencies | The Asterisk modules and third party applications/libraries necessary to run the test | No
expectedResult | The expected result of the test. Setting this to False will cause the test to pass if the test returns failure | No
testconditions | Settings that override the runtests script's test-config.yaml pre/post condition test settings | No
tags | A sequence of tags that categorize the test into groups of similar functionality | No

#### dependencies

Any of the keywords listed below can occur multiple times

Keyword | Description | Required
--- | --- | ---
app | An external application that must be present for the test to execute | No
asterisk | An asterisk module that must be installed for the test to execute | No
buildoption | An option that must be enabled in the Asterisk build for the test to execute | No
pcap | If present, import the yappcap library as a dependency for test execution | No
python | A python module that must be available. Note that an attempt will be made to import the module (using _import_) specified by the value of this keyword | No
sipp | Specifies attributes of SIPp that must be present for this test to execute | No
custom | Execute a custom dependency function. The function must be defined in the Dependency class in the TestConfig module, and must be declared as "depend_%s", where %s is the value specified by the custom keyword | No

##### sipp

Keyword | Description | Required
--- | --- | ---
version | The minimum version of SIPp needed to execute the test
feature | A feature that SIPp must be compiled with in order to execute the test

#### testconditions

Keyword | Description | Required
--- | --- | ---
name | The alias name for the pre/post condition test object whose settings should be overridden | Yes

Each pre/post test condition pair defines their own configuration, and are not documented here.

### test-modules

Keyword | Description | Required
--- | --- | ---
test-object | Defines the primary object that orchestrates test execution | Yes
modules | A sequence that defines optional pluggable modules to inject into the test object | No

#### test-object

Keyword | Description | Required
--- | --- | ---
config-section | The keyword in the test-config.yaml file that provides the configuration for the test object | Yes
typename | The fully qualified package.module.class to instantiate as the test object | Yes

#### modules

Keyword | Description | Required
--- | --- | ---
config-section | The keyword in the test-config.yaml file that provides the configuration for the module | Yes
typename | The fully qualified package.module.class to instantiate as the module | Yes
load-from-path | Optionally, specify the path where the pluggable module should be imported from | No
load-from-test | Optionally, if true, load from the test directory | No
minversion | The minimum version of Asterisk necessary to load the module | No
maxversion | The maximum version of Asterisk that the module can load under | No

The options load-from-path and load-from-test are mutually exclusive.

## Examples

### channels/SIP/info_dtmf

    testinfo:
        summary: 'Test that asterisk properly handles DTMF relayed in SIP INFO requests'
        description: |
            This test checks proper handling of SIP INFO requests containing DTMF events.
            This includes both application/dtmf-relay and application/dtmf content types,
            and checks for DTMF values 0-9, A-D, a-d, *, #, !, and blank message bodies.

    properties:
        minversion: '1.8.0.0'
        dependencies:
            - python : 'twisted'
            - python : 'starpy'
            - sipp :
                version : 'v3.0'
        tags:
            - SIP
            - DTMF

### fax/gateway_mix4

    testinfo:
        summary: 'Test the fax gateway.'
        description: |
            This test verifies proper gateway functionality when a pass through
            t38 negotiation request fails. The sending side will reject the passed
            through negotiation request. The gateway should detect this respond to
            the receiving side as if no failure had occured and then gateway the
            fax.

            The call flow looks like this:
             |send        |
             |g711     t38|
             |----------->|
             |     gateway|
             |t38      t38|
             |<-----------|
            \|receive     |/

    properties:
        minversion: '10.0.0'
        dependencies:
            - python : 'twisted'
            - python : 'starpy'
            - custom : 'fax'
        tags:
            - fax
            - fax_gateway

### cdr/cdr_userfield

    testinfo:
        summary: 'Test that Set(CDR(userfield)=...) works'
        description: |
            'Test that setting the userfield field in the CDR works'

    test-modules:
        test-object:
            config-section: test-object-config
            typename: 'SimpleTestCase.SimpleTestCase'
        modules:
            -
                config-section: 'cdr-config'
                typename: 'cdr.CDRModule'

    test-object-config:
        spawn-after-hangup: True
        test-iterations:
            -
                channel: 'Local/1@default'
                application: 'Echo'

    cdr-config:
        -
            file: 'cdrtest_local'
            lines:
                -
                    source: ''
                    destination: '1'
                    dcontext: 'default'
                    callerid: ''
                    channel: 'Local/1@default-.*'
                    dchannel: ''
                    lastapp: 'Hangup'
                    lastarg: ''
                    disposition: 'ANSWERED'
                    amaflags: 'DOCUMENTATION'
                    userfield: 'bazinga'

    properties:
        minversion: '1.8.0.0'
        dependencies:
            - python : 'twisted'
            - python : 'starpy'
            - asterisk : 'cdr_csv'
        tags:
            - CDR
            - chan_local