USP Scenario Scripting Guide

Much like CWMP Scenario testing available in the tr-069 expansion, USP scenarios can be used to simplify the process of writing test cases to validate the basic behavior of USP enabled devices.

There are two ways to execute USP scenario files.

  1. uspScenarioPath - This testvar can be set to the location of a USP scenario file which will be loaded into CDRouter at start, and run when using the usp-scenarios.tcl module.

  2. uspScenarioBootstrap - This testvar can be set to the location of a USP scenario file which will loaded and run at start. This is a quick and easy way to configure settings on the USP agent before starting any of the other tests.

Syntax

The syntax of a USP scenario is very similar to a CWMP scenario.

Basic Actions Description
Get Sends a USP Get message to the agent from the configured controller.
Set Sends a USP Set message to the agent from the configured controller.
Add Sends a USP Add message to the agent from the configured controller.
Delete Sends a USP Delete message to the agent from the configured controller.
GetSupportedDM Sends a USP GetSupportedDM message to the agent from the configured controller.
GetInstances Sends a USP GetInstances message to the agent from the configured controller.
GetSupportedProtocol Sends a USP GetSupportedProtocol message to the agent from the configured controller.
Operate Sends a USP Operate message to the agent from the configured controller.
Open Opens a connection to the agent from the configured controller.
Delay Pauses execution of the next action for a specified amount of time.
WaitFor Waits for a Notify message of a specific type from the agent.
MetricEval Controls whether or not the actions will trigger PASS or FAIL metrics.

This is a simple example of a script that sets a value and validates that it was set.

USP myScenario {
    Set {
        parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1
    }

    Get {
        parameter Device.LocalAgent.Controller.1.Alias
        verify Device.LocalAgent.Controller.1.Alias "My Controller"
    }
}

Get

This action sends a USP Get message to the configured USP agent, and optionally validates any response.

  • parameter <param>
    • <param> - Parameter to include in the Get message. This value can be any string including invalid paths and search paths.
  • verify <param> <value>
    • <param> - Validate that this parameter is in the GetResp.
    • <value> - Validate that the specified parameter has this value. Regular expressions are accepted.
  • verify_missing <param>
    • <param> - Validate that the specified parameter is not included in the GetResp.
  • expect_error - Expect the last parameter added to this action to fail, will cause a metric fail if it doesn’t.
  • faultcode <value>
    • <value> - If the last parameter added to this action fails, verify the error code matched this value. Use keyword applicable to check that the faultcode is appropriate for a Get message.

Get Example

Get {
    parameter Device.LocalAgent.Controller.
    verify Device.LocalAgent.Controller.1.Alias "My Controller"
    faultcode 7016

    parameter Device.LocalAgent.ParameterThatDoesNotExist
    expect_error

    parameter Device.LocalAgent.Subsription.\[Enable=="true"\].Alias
    verify_missing Device.LocalAgent.Subscription.5.Alias
}

When using the verify command to validate that a parameter returned by the agent matches an expected value there are several options for specifying the expected value.

  • The exact value can be provided, which will be directly compared to the parameter in the GetResp
  • The value [any] can be used to accept any value
  • The value [accept value1 value2] can be used to to accept any of the values provided (value1 or value2 in this example)
  • The value [regexp {[0-9][1-3].+}] can be used to accept any value that matches the provided regular expression

Set

This action sends a USP Set message to the configured USP agent.

  • parameter <param> <value> <required>
    • <param> - Parameter to be set.
    • <value> - Value to set the parameter to.
    • <required> - Boolean 1 or 0 to specify if setting this parameter is required.
  • allow_partial - Sets the allow partial flag on the Set message to true.
  • faultcode <value>
    • <value> - If the agent send and error message as a response, validate the error code matches this value. Use keyword applicable to check that the faultcode is appropriate for a Set message.
  • expect_param_error <param> <faultcode> - This will cause CDRouter to expect a parameter error.
    • <value> - The parameter on which the error is expected to occur.
    • <faultcode> - The faultcode expected from the parameter error. Use keyword applicable to check that the faultcode is appropriate for a Set message.
  • verify_success <param>
    • <param> - Validates that this parameter was successfully set.
  • expect_error - Expect the agent to send an error message.

Set Example

Set {
    parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1
    parameter Device.LocalAgent.ParameterThatDoesNotExist "Bound to Fail" 1
    faultcode 7015
}

Set {
    parameter Device.LocalAgent.ParameterThatDoesNotExist "Bound to Fail" 0
    expect_param_error Device.LocalAgent.ParameterThatDoesNotExists 7010
}

Add

This action sends a Add message to the configured USP agent.

  • path <partial path>
    • <partial path> - This is the path to the table to which a new instance should be added.
  • parameter <param> <value> <required>
    • <param> - Parameter to be set in the newly added instance. This should be the complete path to the parameter, without the last instance number (see example).
    • <value> - Value of the parameter to set.
    • <required> - Boolean 1 or 0 to specify if setting this parameter is required.
  • allow_partial - Sets the allow partial flag on the Add message to true.
  • instance <variable name>
    • <variable name> - Bind the instance number of the newly created object to a variable with this name. This value can be used later by accessing its value via %<variable name>%.
  • faultcode <value>
    • <value> - If an error code is present in the AddResp, validate that it is this value. Use keyword applicable to check that the faultcode is appropriate for a Add message.
  • expect_error - This will cause this action to fail in the event the message succeeds, and will only pass if one the expected faultcodes is returned.
  • expect_partial_failure <faultcode> - This will cause CDRouter to expect a partial failure on the last path referenced with the specified faultcode. Use keyword applicable to check that the faultcode is appropriate for a Add message.
  • expect_param_error <param> <faultcode>
    • <param> - Expect this parameter of an added object to fail to be set.
    • <faultcode> - The expected error code for the failed parameter. Use keyword applicable to check that the faultcode is appropriate for a Add message.

Example Add

Add {
    path Device.LocalAgent.Subscription.
    parameter ReferenceList "Device.IP.Interface.1.Enable" 1
    instance interfaceSubscription

    path Device.LocalAgent.Subscription.
    parameter BadParam "Bad Value" 1
    expect_partial_failure 7017

    allow_partial
}

Delete {
   path Device.LocalAgent.Subscription.%interfaceSubscription%.
}

Delete

This action sends a Delete message to the configured USP agent.

  • path <object>
    • <object> - The path to the instance to delete.
  • allow_partial - Sets the allow partial flag on the Delete message to true.
  • faultcode <value>
    • <value> - If an error code is present in the DeleteResp, validate that it is this value. Use keyword applicable to check that the faultcode is appropriate for a Delete message.
  • expect_error - Except the agent to respond with an error message.
  • expect_partial_failure <faultcode>
    • <faultcode> Expect the last path references in this action to fail with the specified error code. Use keyword applicable to check that the faultcode is appropriate for a Delete message.
  • expect_param_error <param> <code>
    • <param> - Full path to the parameter expected to object expected to fail.
    • <code> - The err_code expected with the associated failure. Use keyword applicable to check that the faultcode is appropriate for a Delete message.

See Add example for usage.

GetSupportedDM

  • path <path>
    • <path> - The requested root for the GetSupportedDM.
  • return_commands - This will request that commands are returned in the GetSupportedDMResp.
  • return_events - This will request that events are returned in the GetSupportedDMResp.
  • return_params - This will request that parameters are returned in the GetSupportedDMResp.
  • verify_param <param>
    • <param> - Validate that this parameter is included in the GetSupportedDMResp.
  • verify_event <event>
    • <event> - Validate that this event is included in the GetSupportedDMResp.
  • verify_command <command>
    • <command> - Validate that this command is included in the GetSupportedDMResp.
  • faultcode <faultcode> - If the agent responds with an error message, ensure the error code matches the specified faultcode. Use keyword applicable to check that the faultcode is appropriate for a GetSupportedDM message.
  • expect_error - Expect the agent to send an error message.

Example GetSupportedDM

GetSupportedDM {
    path Device.
    return_commands
    return_params
    return_events

    verify_param Device.DeviceInfo.ModelVersion
    verify_event Device.Boot!
    verify_command Device.Reboot()
}

GetInstances

This action sends a GetInstances message to the configured USP agent

  • path <path>
    • <path> - Requested root for the GetInstances message.
  • first_level_only - This will cause the first_level_only flag in the GetInstances message to be set to ’true'.
  • faultcode <faultcode> - If the agent responds with an error message, ensure the error code matches the specified faultcode. Use keyword applicable to check that the faultcode is appropriate for a GetInstances message.
  • expect_error - Expect the agent to send an error message.

Example GetInstances

GetInstances {
    path Device.
}

GetSupportedProtocol

This action sends a GetSupportedProtocol message to the configured USP agent

  • expect_error - Expect the agent to send an error message.

Example GetSupportedProtocol

USP myScenario {
    GetSupportedProtocol
}

Operate

This action sends an Operate message to the configured USP agent

  • operation <name>
    • <name> - The full path of the command to be executed.
  • arg <name> <value>
    • <name> - The name of the argument.
    • <value> - The value of the argument.
  • command_key <value>
    • <value> - The command key to use for this Operate message.
  • send_resp <value>
    • <value> - Boolean 0 or 1 controlling the value the send_resp field is set to in the Operate message.
  • faultcode <value>
    • <value> - If an error code is present in the OperateResp, validate that it is this value. Use keyword applicable to check that the faultcode is appropriate for an Operate message.
  • expect_error - This will cause this action to fail in the event the message succeeds, and will only pass if one the expected faultcodes is returned.

Example Operate

USP myScenario {
    Operate {
        operation Device.DeviceInfo.VendorLogFile.4.Upload()
        arg URL http://200.23.0.22
        arg Username qacafe
        arg Password qacafe123
        faultcode 7022
    }
}

Delay

Add a delay between actions

Example Delay

USP myScenario {
    Set {
        parameter Device.LocalAgent.Controller.1.Alias "My Controller" 1   
    }

    Delay 10

    Get {
        parameter Device.LocalAgent.Controller.1.
        verify Device.LocalAgent.Controller.1.Alias "My Controller"
    }
}

WaitFor

Wait for a notification from the configured USP agent and validates the values.

  • ValueChange - Waits for a ValueChange notification.
    • verify_path <path> - Ensures this path is included in the notification.
    • verify_value <value> - Validate that the value of specified path matches this.
  • Event - Waits for an Event notification.
    • verify_path <path> - Validate that the event path matches <path>.
    • verify_name <event_name> - Validate that the event name matches <event_name>.
    • verify_arg <name> <value> - Validate that argument <name> is <value>.
  • ObjectCreation - Waits for an ObjectCreation notification.
    • verify_path <path> - Validate that the path in the notification matches <path>.
    • verify_key <name> <value> - Validate that the key value pair <name>,<value> is among the keys.
  • ObjectDeletion - Waits for an ObjectDeletion notification.
    • verify_path <path> - Validates that <path> is in the notification.
  • OperationComplete - Waits for an OperationComplete notification.
    • verify_path <path> - Validates that <path> is in the notification.
    • verify_command_key <name> - Validates the command key in the notification is <name>.
    • verify_command_name <name> - Validates the command name in the notification is <name>.
    • verify_arg <name> <value> - Validated that key value pair <name>, <value> is among the arguments in the notification.
  • OnBoardRequst - Waits for an OnBoardRequst notification.
    • verify_oui <oui> - Validates the OUI in the OnBoadReqest matches <oui>.
    • verify_product_class <product_class> - Validates the product class in the OnBoadReqest matches <product_class>.
    • verify_serial_number <serial_number> - Validates the serial number in the OnBoadReqest matches <serial_number>.
    • verify_protocol_version <version> - Validates the version in the OnBoadReqest matches <version>.
  • timeout <seconds> - Sets the timeout for waiting for the specified notification. The default timeout is 60 seconds.

Example WaitFor:

Add {
    path Device.LocalAgent.Subscription.
    parameter ReferenceList Device.DeviceInfo.UpTime
    parameter Enable true
    parameter NotifType ValueChange
}

WaitFor {
    ValueChange {
        path Device.DeviceInfo.UpTime
    }
}

MetricEval

Turns on or off metric evaluations for actions after this command.

MetricEval off

Set {
    parameter Device.SomeParameterThatMightNotExist "My Value"
}

MetricEval on

New Test Case Support for Scenarios

USP scenarios introduces the ability to use scenarios inline in test cases. This can greatly improve the readability of simple operations while still providing the flexibility of more complex actions.

An inline scenario is used by calling USP_scenario_with_stack and giving it a valid USP controller stack. USP_scenario_with_stack <stack> <scenario>

USP_scenario_with_stack uspServer {
    Log {"Starting test setup"}
    Add {
        path Device.LocalAgent.Subscription.
        parameter NotifyRetry false 1
        instance sub1
    }
}