rpc.mpl
rpc.mpl |
|
rpc.mpl - an RPC interface for the ApTest Manager test execution area
http://example.com/atm/run/rpc.mpl?rpctoken=token&username=name& \
suite=suiteName&command=commandName...
rpc.mpl provides a simple Remote Procedure Call interface to allow basic run operations to be performed over the internet by external tools.
Using your web browser, go to the Manage ApTest Manager screen, and click on Manage System Configuration. Enter a value for "What is the authentication token for users of the RPC interface?". You will not be able to use the RPC interface until a token is set.
RPC calls can be made using GET or POST requests. POST is suggested if you wish to keep the RPC authentication token out of the server's access logs.
External tools pass in an authentication token to verify that they can access the RPC interface. There is a single token for all tools. The tool also passes a username. Assuming the tool authenticated correctly, it performs its actions as the specified user. The user will need to have at least "run" access to the suite being operated on.
The server will return a response of type text/plain. The first line will be a numeric return code (currently 0 for success or 1 for an error) followed by zero or more message lines. In the event of an error, the message will detail the error.
Create a set group.
Example: Create set group called "Group_C" within an existing set group called "Group_A/Group_B":
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createGroup& \
name=Group_C&setGroup=Group_A/Group_B
Create a test set, optionally setting test case and requirement selectors, and default schedules and session variable settings.
The message line of the return value will be the number of tests selected in the new set.
Example: Create a set called "My_Set" in set group "Group_A/Group_B" containing high priority test cases:
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createSet& \
set=My_Set&setGroup=Group_A/Group_B&SCHEMA_priority=high
Create a test session, based on a test set. Optionally set schedules and session variables.
The message line of the return value will be the session number of the new session.
Example: Create a session from Group_A/Group_B/My_Set, scheduled to start on 1 February 2009, for Mac OS 9:
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=createSession& \
set=Group_A/Group_B/My_Set&startdateplanned=1233446400&VAR_os=Mac_OS_9
Fetch the UUID associated with a requirement.
The message line of the return value will be the UUID for the named requiement, or empty of the requirement was not found.
Example: Get the UUID for a requirement using outline numbering with number '1.0.1'
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getReqUUID& \
name=1.0.1
Fetch the status of a test session.
The message line of the return value will be a collection of semi-colon separated key / value pairs reporting the number of tests in the session, and the number of tests that have each result defined for the suite.
Example: Get the status for session 2
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=geSessionStatus& \
sessnum=2
Fetch the list of Test Cases associated with a session or set.
The message lines of the return value will a test case ID or UUID, one per line, for each test case included in the requested test session or set.
Example: Get the list from set 'performance' in UUID form
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestList& \
set=performance&byUUID=1
Fetch the UUID associated with a test case.
The message line of the return value will be the UUID for the named test case, or empty of the test case was not found.
Example: Get the UUID for a test case using 'plain' naming with a name of 'test/more/foo'
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=getTestUUID& \
name=test/more/foo
Set a result and/or notes and execution data for a test in a session.
If a result is specified, the entry will be classified as a "test execution"; if no result is specified, the entry will be classified as a "note".
Note that any existing values in execution data fields will be preserved when setting a result or note using this command, so you can use it to change the value of an execution data field without having to resubmit all the current execution data.
If a note or result is supplied, then the default time stamp for the result will be the time the result/note is submitted. You can override this via the execdata_when parameter - execdata_when takes seconds since the epoch.
If a note or result is supplied, then the default user to associate with it will be the value of the required username parameter. You can override this via the execdata_user parameter.
The message line of the return value will be an HTML fragment describing the note or result.
Example: Set the result of the first test case in the session to "retest":
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \
sess=00001&tid=0&result=retest
Example: Change the atm_prid field in the "ATM_Administration/Help_Screen" test case to "42":
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \
sess=00001&id=ATM_Administration.dir/Help_Screen.bts& \
EXECDATA_prid=42
Example: Add a note - "Fixed" - to the test case with UUID AC2CD7D2-955D-11D8-A214-90E5C9F5B464:
rpc.mpl?rpctoken=token&username=lake&suite=Example&command=result& \
sess=00001&uuid=AC2CD7D2-955D-11D8-A214-90E5C9F5B464¬e=Fixed \
The following arguments are common to all requests, and are mandatory.
The authentication token for RPC tools, as set in the System Configuration (described above).
The ApTest Manager username of the user in whose name the command will be executed. The user must have at least run access to the suite in question.
The suite to operate on.
The command to execute. Each command has specific additional arguments. Available commands are createGroup, createSet, createSession, and result.
The name of the set group to create.
Set group description
The name of the group to create the new group in. Defaults to the root set group.
The name of the set to create
The name of the set group to create the set in. Defaults to the root set group.
The description to add to the set.
Default planned start and end dates for sessions created from the set.
Value is in "seconds since the epoch".
Default start and end date "on time" windows for sessions created from the set.
Valid values are 14400, 28800, 57600, 86400, 172800, 259200, and 604800 (4, 8, 16, and 24 hours, and 2, 3, and 7 days respectively).
Test case field selectors. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl
Requirement field selectors. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl
Default session variables for sessions created from this set. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl
The name of the set in which to create the session.
A name to give the session.
A description for the session.
Planned start and end dates for the session.
Value is in "seconds since the epoch".
Start and end date "on time" windows for the session.
Valid values are 14400, 28800, 57600, 86400, 172800, 259200, and 604800 (4, 8, 16, and 24 hours, and 2, 3, and 7 days respectively).
Session variables for the session. Values are formatted as they would be when submitted from the HTML form at run/defineSet.mpl
The name of the requirement. If the suite's requirements are in auto-outline mode, then this is the outline number. Otherwise it is the name of the requirement, including the path (e.g. top/sub/requirement_name).
The number of the test session on which to report.
The session number or the complete set name (including folders) to list.
A boolean. If true, return the list of test case UUIDs. If false, return the list of test case IDs. Defaults to false.
The name of the test case. If the suite's test cases are in auto-outline mode, then this is the outline number. Otherwise it is the name of the test case, including the path (e.g. top/sub/test_name).
The session number to operate on.
The test case index in the session (zero-indexed - first test is 0, second is 1, etc.).
The ID of the test case (the path to the test case in the file system, e.g. "Example.dir/Test_case.bts").
The UUID of the test case. This uniquely identifies the test case within the suite, and so is a reliable identifier which will not be affected by renaming the test case or reordering the session.
The UUID of a test case is one of the parameters that may be passed to a bug-tracking system in the bug-tracking system integration link.
A note to apply. Defaults to an empty string.
A result to set. If omitted, the change will be marked as a "note" rather than a test execution.
Execution data field values, formatted as if submitted from a web form.
Copyright © 2000-2011 Applied Testing and Technology, Inc. All rights reserved.