Menu ▾ ▴

WTL Script Commands

Jose Guterman

=Script Commands=

The following sections describe in detail the basic script commands which are grouped in the following functional categories:

WITSML Store: Commands to implement the basic WITSML Store API function calls

Verify: Commands to perform checking on the result of the WITSML Store API functions

Parse: Commands to retrieve information from the responses received from the WITSML server

Execution Control: Commands to control the execution of the Test Scripts

Miscellaneous: Other general utility commands

==WITSML Store Script Commands==

Script commands exist for each of the WMLS store API functions (see subsections below).

Each script command will generate the corresponding WITSML request to the server and wait for a response. If a response is not received the test will fail.

If a response is received, the corresponding response values are stored into runtime variables. The following runtime variables are be defined for this purpose

  • ‘result’ to store the ReturnValue
  • ‘xml_out’ to store the XMLout
  • If included, the ‘logData’ is stored in a separate runtime variable within ‘xml_out’
  • ‘capabilities_out’ to store the CapabilitiesOut
  • ‘supp_msg_out’ to store the SuppMsgOut

Even though WITSML store script commands can be run in a Test Suite file, they are meant to be used within the Test Scripts or interactively in a python interpreter.

For definition of each of the parameters used in each script command see section 3.2.

WMLS_AddToStore (WMLtypeIn, XMLin, OptionsIn={CapabilitiesIn=””)

Description: Send a WMLS_AddToStore request to the server with the provided parameters and wait for the response.

If a response is not received the test fails. If a response is received, set the runtime variables __ReturnValue, and __SuppMsgOut accordingly

Parameters: WMLtypeIn: A string containing the object type

XMLin: A string containing an XML document with the add request

OptionsIn: An optional list of options

CapabilitiesIn: An optional string containing an XML document with the client’s capabilities

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example: 

WMLS_AddToStore(‘well’, “@<nowiki>add_to_store_query_1.xm</nowiki>l@”)

===WMLS_DeleteFromStore(WMLtypeIn, QueryIn, OptionsIn={}, CapabilitiesIn=””)===

Description: Send a WMLS_DeleteFromStore request to the server with the provided parameters and wait for the response.

If a response is not received the test fails. If a response is received, set the runtime variables __ReturnValue, and __SuppMsgOut accordingly

Parameters: WMLtypeIn: A string containing the object type

QueryIn: A string containing an XML document with the delete request

OptionsIn: An optional list of options

CapabilitiesIn: An optional string containing an XML document with the client’s capabilities

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example:

WMLS_DeleteFromStore(‘log’, “@<nowiki>delete_from_store_query_1.xm</nowiki>l@”)

===WMLS_GetBaseMsg(ReturnValueIn)===

Description: Send a WMLS_GetBaseMsg request to the server with the provided parameters and wait for the response.

If a response is not received the test fails. If a response is received, set the runtime variable __ReturnValue accordingly

Parameters: ReturnValueIn: Integer containing a return value

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example:

WMLS_GetBaseMsg(RETURNVALUE_FUNCTION_COMPLETED_SUCCESSFULLY)

===WMLS_GetCap(OptionsIn={})===

Description: Send a WMLS_GetCap request to the server with the provided parameters and wait for the response.

If a response is not received, the test fails. If a response is received, set the runtime variables __ReturnValue, and __CapabilitiesOut accordingly

Parameters: OptionsIn: An optional list of options

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example:

WMLS_GetCap(OptionsIn={‘dataVersion’:”1.3.1.1”})

===WMLS_GetFromStore(WMLtypeIn, QueryIn, OptionsIn={}, CapabilitiesIn=””)===

Description: Send a WMLS_GetFromStore request to the server with the provided parameters and wait for the response.

If a response is not received the test fails. If a response is received, set the runtime variables __ReturnValue, __XMLout and __SuppMsgOut accordingly

Parameters: WMLtypeIn: A string containing the object type

QueryIn: A string containing an XML document with the get request

OptionsIn: An optional list of options

CapabilitiesIn: An optional string containing an XML document with the client’s capabilities

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example:

WMLS_'''GetFromStore(WMLTYPEIN_WELL,'''

''' """<wells xmlns=”''''''[http://www.witsml.org/schemas/131ex ]http://www.witsml.org/schemas/131ex''''''”'''

''' version=”1.3.1.1”>'''

''' <well uid<nowiki>=''> </nowiki>'''

''' <name/> '''

''' </well> '''

''' </wells>”””,'''

            OptionsIn={‘returnElement’:’all’})

===WMLS_GetVersion()===

Description: Send a WMLS_GetVersion request to the server with the provided parameters and wait for the response.

If a response is not received the test fails. If a response is received, set the runtime variable __ReturnValue'' ''accordingly

Parameters: None

Return: None.

Script will fail if a response is not received

Example:

WMLS_GetVersion()

===WMLS_UpdateInStore(WMLtypeIn, XMLin, OptionsIn={}, CapabilitiesIn=””)===

Description: Send a WMLS_UpdateInStore request to the server with the provided parameters and wait for the response.

If a response is not received, the test fails. If a response is received, set the runtime variables __ReturnValue and __SuppMsgOut accordingly

Parameters: WMLtypeIn: A string containing the object type

XMLin: A string containing an XML document with the update request

OptionsIn: An optional list of options

CapabilitiesIn: An optional string containing an XML document with the client’s capabilities

See also section 3.2.

Return: None.

Script will fail if a response is not received

Example:

WMLS_'''UpdateInStore(WMLTYPEIN_WELL,”@<nowiki>update_query1.xm</nowiki>l@”''')

==Verify Script Commands==

These script commands verify the content of the runtime variables that are populated as a result of receiving a response from the WITSML server. These script commands will make a script fail if the corresponding condition is not matched.

The verify script commands are of the following form:

'''check_'''<runtime variable>'''_'''<function>

where:

<runtime variable> is one of the result runtime variables:

ReturnValue

SuppMsgOut

CapabilitiesOut

XMLout

logData

<function> is one of the function defined in the following sections

For example:

check_ReturnValue_Success

check_SuppMsgOut_Contains

check_CapabilitiesOut_String

check_CapabilitiesOut_ElementIncluded

check_XMLout_XMLString

check_XMLout_RecurringElementValue

check_XMLout_AttributeValue

check_logData_NumberOfNodes

The following sections describe all the available <function> values. Each function is described including:

  • Description of the function
  • Parameters
  • Example
  • Runtime variables for which the function can be used

Even though verify script commands can be run in a Test Suite file, they are meant to be used within the Test Scripts or interactively in a python interpreter.

===Success()===

Description: Verifies that the ReturnValue indicates success (i.e. ReturnValue > 0)

Parameters: None

Return: None.

Script will fail if the check fails

Example:

WMLS_GetCap()

check_ ReturnValue_Success()

Can be used with runtime variables: ReturnValue

===Failure()===

Description: Verifies that the ReturnValue indicates failure (i.e. ReturnValue < 0)

Parameters: None

Return: None.

Script will fail if the check fails

Example:

WMLS_GetCap()

check_ ReturnValue_Failure()

Can be used with runtime variables: ReturnValue

===Value(expected_return_value)===

Description: Verifies that the corresponding variable matches the given integer value.

Parameters: expected_return_value: The expected variable contents

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_WELL,

              """&lt;wells xmlns=”<nowiki>http://www.witsml.org/schemas/131ex</nowiki>”

                        version=”1.3.1.1”&gt;

                   &lt;well uid<nowiki>=''&gt;     </nowiki>

                     &lt;name/&gt;

                   &lt;/well&gt;

                 &lt;/wells&gt;

              """)

check_ReturnValue_Value(1)

Can be used with runtime variables: ReturnValue

===String(expected_string)===

Description: Verifies that the corresponding variable matches the given string. For variables containing XML documents, the empty text between tags is ignored.

Parameters: expected_string: The expected variable contents

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetBaseVersion()

check_ ReturnValue_String(‘1.2,1.3.1.1’)

WMLS_GetFromStore(WMLTYPEIN_WELL,

              """&lt;wells xmlns=”<nowiki>http://www.witsml.org/schemas/131ex</nowiki>”

                        version=”1.3.1.1”&gt;

                   &lt;well uid<nowiki>=''&gt;     </nowiki>

                     &lt;name/&gt;

                   &lt;/well&gt;

                 &lt;/wells&gt;

              """)

check_XMLout_String(‘.<well uid=”ca_4001”>.’)

Can be used with runtime variables: ReturnValue, SuppMsgOut, CapabilitiesOut, XMLout

===Contains(expected_substring)===

Description: Verifies that the corresponding variable contains the provided string. This is the equivalent of ''check_<runtime variable>_String(“.expected_substring.”)''

Parameters: expected_substring: The substring that is expected to be contained within the variable

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetBaseVersion()

check_ ReturnValue_Contains(‘1.3.1.1’)

Can be used with runtime variables: ReturnValue, SuppMsgOut, CapabilitiesOut, XMLout

===XMLString(expected_xml_string)===

Description: Verifies that the corresponding variable contents match the given XML document. The empty text between tags is ignored.

Parameters: expected_xml_string: A well-formed XML document containing the contents to be checked

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_WELL,

              """&lt;wells xmlns=”<nowiki>http://www.witsml.org/schemas/131ex</nowiki>”

                        version=”1.3.1.1”&gt;

                   &lt;well uid<nowiki>=''&gt;     </nowiki>

                     &lt;name/&gt;

                   &lt;/well&gt;

                 &lt;/wells&gt;

              """)

check_XMLout_XMLString("""<wells xmlns=”<nowiki>http://www.witsml.org/schemas/131ex</nowiki>”

                          version=”1.3.1.1”&gt;

                     &lt;well uid='cas_12345678'&gt;

                       &lt;name&gt;Well 1&lt;/name&gt;

                     &lt;/well&gt;

                   &lt;/wells&gt;

                """)

Can be used with runtime variables: CapabilitiesOut, XMLout

===ElementIncluded(element)===

Description: Verifies that the corresponding variable contains an element with the provided tag name. As long as there is one instance of that element at any level in the XML document the verify script command will succeed

Parameters: element: tag name of the element to be checked.

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the r</nowiki>esponse includes the ‘name’ element

check_XMLout_ElementIncluded('name')

Can be used with runtime variables: CapabilitiesOut, XMLout

===ElementNotIncluded(element)===

Description: Verifies that the corresponding variable does not contain an element with the provided tag name. If there is one instance of that element at any level in the XML document the verify script command will fail

Parameters: element: tag name of the element to be checked.

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the r</nowiki>esponse does not include the ‘name’ element

check_XMLout_ElementNotIncluded('name')

Can be used with runtime variables: CapabilitiesOut, XMLout

===ElementValue(element, expected_string)===

Description: Verifies that the corresponding variable contains an element with the provided text. If more than one instance of that element is included in the XML document the first instance is checked

Parameters: element: tag name of the element to be checked.

expected_string: The expected text of the element with the specified tag

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>‘name’ value of the well

check_XMLout_ElementValue('name', ‘My well name’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===ElementValueContains(element, expected_substring)===

Description: Verifies that the corresponding variable contains an element with text containing the expected string. If more than one instance of that element is included in the XML document the first instance is checked

Parameters: element: tag name of the element to be checked.

expected_substring: The string expected to be included in the text of the element with the specified tag

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>well ‘name’ contains the word ‘WELL’

check_XMLout_ElementValueContains('name', ‘WELL’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===ElementValueIsContained(element, expected_superstring)===

Description: Verifies that the corresponding variable contains an element with text that is included in the provided string. If more than one instance of that element is included in the XML document the first instance is checked

Parameters: element: tag name of the element to be checked.

expected_superstring: The string that contains the text of the element with the specified tag

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>well ‘name’ is contained in the list of names

check_XMLout_ElementValueIsContained('name', ‘WELL 1;WELL 2;WELL 3;WELL 4’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===RecurringElementValue(element, expected_list)===

Description: Verifies that the corresponding variable contains a recurring element with the values provided in the list

Parameters: element: tag name of the recurring element to be checked.

expected_list: List of values expected for the element with the specified tag

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetCap({‘dataVersion’:”1.3.1.1”})

<nowiki># Check the </nowiki>list of objects supported

check_CapabilitiesOut_RecurringElementValue('dataObject'<nowiki>, [‘</nowiki>log’,’well’])

Can be used with runtime variables: CapabilitiesOut, XMLout

===AttributeIncluded(element, attribute)===

Description: Verifies that the corresponding element contains an attribute with the provided name. The first instance of the element is checked

Parameters: element: tag name of the element to be used.

attribute: name of the attribute to check

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the r</nowiki>esponse includes the ‘version’ attribute for the ‘wells’ element

check_XMLout_AttributeIncluded('wells', ‘version’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===AttributeNotIncluded(element, attribute)===

Description: Verifies that the corresponding element does not contain an attribute with the provided name. The first instance of the element is checked

Parameters: element: tag name of the element to be used.

attribute: name of the attribute to check

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the r</nowiki>esponse doesn’t include a ‘version’ attribute for the ‘wells’ element

check_XMLout_AttributeNotIncluded('wells', ‘version’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===AttributeValue(element, attribute, expected_string)===

Description: Verifies that the corresponding element has an attribute with the provided value. The first instance of the element is checked

Parameters: element: tag name of the element to be used.

attribute: name of the attribute to check

expected_string: expected value of the attribute

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>correct ‘version’ attribute is received for the ‘wells’ element

check_XMLout_AttributeValue('wells', ‘version’, ‘1.4.1.0’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===AttributeValueContains(element, attribute, expected_substring)===

Description: Verifies that the corresponding element has an attribute with a value that contains the provided string. The first instance of the element is checked

Parameters: element: tag name of the element to be used.

attribute: name of the attribute to check

expected_substring: string expected to be contained by the attribute’s value

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>‘version’ attribute for the ‘wells’ elementcontains ‘1.4’

check_XMLout_AttributeContains('wells', ‘version’, ‘1.4’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===AttributeValueIsContained(element, attribute, expected_superstring)===

Description: Verifies that the corresponding element has an attribute with a value which is contained within the provided string. The first instance of the element is checked

Parameters: element: tag name of the element to be used.

attribute: name of the attribute to check

expected_superstring: string expected to be contain the attribute’s value

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

<nowiki># Well query</nowiki>

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check the </nowiki>‘version’ attribute for the ‘wells’ is one of the list

check_XMLout_AttributeIsContained('wells', ‘version’, ‘1.4.1.0 - 1.3.1.1’)

Can be used with runtime variables: CapabilitiesOut, XMLout

===NumberOfObjects(n)===

Description: Verify that the XMLout contains the expected number of objects

Parameters: n: number of objects expected in XMLout.

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_WELL, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Verify that only a single object was received</nowiki>

check_XMLout_NumberOfObjects(1)

Can be used with runtime variables: XMLout

===IndexValue(row_index, index_value, error_margin=0)===

Description: Verify that the corresponding data index value matches the value provided. For Depth index, an optional error margin can be provided for the comparison.

Parameters: row index: relative row number in the logData

index_value: value to be checked

error_margin: Percent margin of error for comparison (i.e. value will be correct if within +/-error_margin% of the index_value)

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check that the time start index is “2011-07-10T17:00:00-07:00”</nowiki>

check_logData_IndexValue(0, “2011-07-10T17:00:00-07:00”)

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query2.xm</nowiki>l@”)

<nowiki># Check that the depth start index is within 90 and 110m</nowiki>

check_logData_IndexValue(0, 100, 10)

Can be used with runtime variables: logData

===DataValue(row_index, mnemonic, data_value, error_margin=0)===

Description: Verify that the corresponding data value matches the value provided. For numeric data values, an optional error margin can be provided for the comparison.

Parameters: row index: relative row number in the logData

mnemonic: curve to be checked

value: value to be checked

error_margin: Percent margin of error for comparison (i.e. value will be correct if within +/-error_margin% of the index_vale)

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check that the TIME curve in the second row is “2011-07-10T17:00:00-07:00”</nowiki>

check_logData_DataValue(2, ‘TIME’, “2011-07-10T17:00:00-07:00”)

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query2.xm</nowiki>l@”)

<nowiki># Check that the first ROP value is within 90 and 110</nowiki>

check_logData_DataValue(0, ‘ROP’, 100, 10)

Can be used with runtime variables: logData

===NumberOfNodes(num_nodes)===

Description: Verify that the logData has the corresponding number of nodes

Parameters: num_nodes: expected number of nodes

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check that 100 nodes are returned</nowiki>

check_logData_NumberOfNodes(100)

Can be used with runtime variables: logData

===NumberOfPoints(num_points)===

Description: Verify that the logData has the corresponding number of data points

Parameters: num_points: expected number of data points

See also section 3.2.

Return: None.

Script will fail if the check fails

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># Check that 1000 data points are returned</nowiki>

check_logData_NumberOfPoints(1000)

Can be used with runtime variables: logData

==Parse Script Commands==

These script commands retrieve information from the runtime variables that get set a result of receiving a response from the WITSML server. These script commands return a value of the type specified in the primitive. A ''null string'' for a String, an ''empty list'' for a List and ''0'' for an Integer are returned if the value cannot be obtained.

The parse script commands are of the following forms:

'''get_'''<runtime variable>''''''<function><type>

where:

<runtime variable> is one of the result runtime variables:

ReturnValue

SuppMsgOut

CapabilitiesOut

XMLout

logData

<function> is one of the function defined in the following sections

<type> is one of

String

List

Int

For example:

get_XMLout_Element_String

get_CapabilitiesOut_RecurringElement_List

get_logData_IndexValue_String

The following sections describe all the available <function> values. Each function is described including:

  • Description of the function
  • Parameters
  • Example
  • Runtime variables for which the function can be used

Even though parse script commands can be run in a Test Suite file, they are meant to be used within the Test Scripts or interactively in a python interpreter.

===Element_String(element)===

Description: Returns a string containing the value of the element specified. If the element is of a specific type, it can be converted with the corresponding function:

  • To convert to an Integer use int''()''
  • To convert to a floating point number use ''float()''

Parameters: element: tag name of the element requested

See also section 3.2.

Return: The string containing the elements value or an empty string if the element does not exist

Examples:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># </nowiki>Set a variable x with the name of the log received

set(‘x’, get_XMLout_Element_String(‘name’))

<nowiki># </nowiki>Check that the ‘changeDetectionPeriod’ (an integer) is not more than 600

WMLS_GetCap(OptionsIn={'dataVersion':'1.3.1.1'})

if (int(get_CapabilitiesOut_Element_String('changeDetectionPeriod')) > 600):

fail("changeDetectionPeriod is greater than 10 minutes")

Can be used with runtime variables: CapabilitiesOut, XMLout

===RecurringElement_List(element)===

Description: Returns a list of strings containing the values of the recurring element specified

Parameters: element: tag name of the recurring element requested

See also section 3.2.

Return: A list of strings containing the elements value or an empty list if the element does not exist

Example:

WMLS_GetCap(OptionsIn={‘dataVersion’:”1.3.1.1”})

get_CapabilitiesOut_RecurringElement_List(‘dataObject')

Can be used with runtime variables: CapabilitiesOut, XMLout

===IndexValue_String(row_index)===

Description: Returns the value of the index curve from a row in the logData

Parameters: row index: relative row number in the logData

See also section 3.2.

Return: A string with the index curve value

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># </nowiki>Set a variable x with the start index

set(‘x’, get_logData_IndexValue_String(0))

Can be used with runtime variables: logData

===DataValue_String(row_index, mnemonic)===

Description: Returns the value of a curve from a row in the logData

Parameters: row index: relative row number in the logData

mnemonic: curve to be retrieved

See also section 3.2.

Return: A string with the index curve value

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

<nowiki># </nowiki>Set a variable x with the 3rd value of ROP

set(‘x’, get_logData_DataValue_String(2,’ROP’))

Can be used with runtime variables: logData

===NumberOfNodes_Int()===

Description: Return the number of nodes in the logData

Parameters: None

Return: An integer with the number of nodes

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

get_logData_NumberOfNodes_Int()

Can be used with runtime variables: logData

===NumberOfPoints_Int()===

Description: Return the number of data points in the logData

Parameters: None

Return: An integer with the number of data points

Example:

WMLS_GetFromStore(WMLTYPEIN_LOG, "@<nowiki>query1.xm</nowiki>l@”)

get_logData_NumberOfPoints_Int()

Can be used with runtime variables: logData

==Execution Control Script Commands==

The execution control script commands implement control the execution and the result of Test Scripts and Test Suites. Execution control script commands are defined in separate sections based on whether they can be used in a Test Script or Test Suite

===Execution Control Script Commands: Test Script===
====fail(fail_string)====

Description: Indicate that the current Test Script being executed failed and the Test Script will stop execution.

Parameters: ''fail_string:'' A string to be sent to the output and to the logging file. This string will give details of the cause of the failure or capture any other desired information such as the time of the failure, tool setting or other parameters.

When a Test Script stops execution as a result of a ''fail'' command, the result of the tests is FAIL.

Return: None

Example:

fail(‘Value for element <name> is different than expected’)

====partial_success(success_string)====

Description: Indicate that a partial success in the current Test Script occurred and continue with the test execution. This allows indication of partial success criteria during test execution.

Parameters: success''_string:'' A string to be sent to the output and to the logging file. This string will give details of the success achieved or capture any other desired information such as the time, tool setting or other parameters.

Return: None

Example:

partial_success(‘Received correct schema version’)

====success()====

Description: Indicate that the current Test Script being executed succeeded and stop execution of the Test Script. This command is implicitly executed is the Test Script reaches the end of the file without a failure.

When a Test Script stops execution as a result of a ''success'' command, the result of the tests is PASS.

Parameters: None

Return: None

Example:

success()

====stop()====

Description: Stop execution of the Test Script.

When a Test Script stops execution as a result of a ''stop'' command, the result of the tests is INCONCLUSIVE.

Parameters: None

Return: None

Example:

stop()

====error()====

Description: Indicate an error was detected and stop execution of the Test Script.

When a Test Script stops execution as a result of an ''error'' command, the result of the tests is FAIL.

Parameters: None

Return: None

Example:

error(‘Bad value detected’)

====execute(script_name, param1=value1, param2=value2)====

Description: Execute the specified Test Script with the given parameters. The test will end with a result of PASS, FAIL or INCONCLUSIVE.

If the script being run fails, the script executing this command will also fail.

Parameters can be hardcoded values like ‘well 1’ or variable contents like ‘$var_name$’

Note: Test Script parameters are defined in the Test Script header. See section 2.2.1. All Test Script parameters must be included in the ''run'' command with a value.

Parameters: ''script_name:'' The name of the Test Script file to be run without the ‘.py’ extension

''param1=value1: ''A script parameter with the corresponding value

Return: None

Examples:

execute(‘script1’, well_id=’w12345’, version=‘$server_schem_version$’)

execute(‘script2’)

===Execution Control Script Commands: Test Suite ===
====run(script_name, param1=value1, param2=value2)====

Description: Execute the specified Test Script with the given parameters. The test will end with a result of PASS, FAIL or INCONCLUSIVE.

Failure of the test being run will not cause the script executing this script command to fail (Note: The way that a failure is handled by the ‘run’ command is what makes it different from the ‘execute’ command)

Parameters can be hardcoded values like ‘well 1’ or variable contents like ‘$var_name$’

Note: Test Script parameters are defined in the Test Script header. See section 2.2.1. All Test Script parameters must be included in the ''run'' command with a value.

Parameters: ''script_name:'' The name of the Test Script file to be run without the ‘.py’ extension

''param1=value1: ''A script parameter with the corresponding value

Return: None

Examples:

run(‘script1’, well_id=’w12345’, version=‘$server_schem_version$’)

run{‘script2’)

====get_last_test_result()====

Description: Get the result of the last Test Script run. This can be used to decide how to continue execution of Test Scripts.

Parameters: None

Return: One of PASS, FAIL or INCONCLUSIVE

Examples:

if (get_last_test_result() == FAIL):

end()

====end(exit_code)====

Description: Ends the execution of the Test Suite.

Parameters: exit_code'':'' Code to use as result when terminating execution. This can be used by an application running the Test Suite.

Return: None

Examples:

end()

==Miscellaneous Script Commands==
===set(var_name, var_value)===

Description: Set a variable with the corresponding value. Variable can be used in a number of commands (See section 3.2).

Parameters: var_name'':'' Name of the variable to set.

var_value'':'' Value to set the variable to.

Return: None

Example:

set(‘well_id’, ‘w12345’)

===get(var_name)===

Description: Get the value of a variable.

Parameters: var_name'':'' Name of the variable to get the value from.

Return: Value of the variable

Example:

if(get(’well_id’) == ‘w12345’)):

fail()

===now()===

Description: Return a WITSML date-time string with the current time.

Parameters: None

Return: The WITSML date-time string

Example:

<nowiki>#Set the ‘time’ variable with the current time</nowiki>

set(‘time’, now())

===logging_on()===

Description: Turn logging on. Any call to ''log'' or ''log_variable'' will put the corresponding information in the log file.

Parameters: None

Return: None

Example:

<nowiki># Turn on logging</nowiki>

logging_on()

===logging_off()===

Description: Turn logging off. Any call to ''log'' or ''log_variable'' will not put the corresponding information in the log file.

Parameters: None

Return: None

Example:

<nowiki># Turn off logging</nowiki>

logging_off()

===log(log_string, force=False, no_new_line<nowiki>=False, prefix=''</nowiki>)===

Description: Add the provided string to the log file.

The string provided is pre-pended with ‘#” to allow identification of script generated log strings in the final log file.

Parameters: log _string'':'' String to be logged

''force:'' If this parameter is provided with a ''True'' value, the string is logged independent on the logging status (i.e. ignore a logging_off() command)

no_new_line'':'' If this parameter is provided with a ''True'' value, no new line is added after the log string. Otherwise a new line is added.

prefix'':'' A prefix string to be added in from of the string to be logged. Nothing is this parameter is not provided

Return: None

Example:

The following commands:

log(‘Add this string to the log’)

logging_off()

log(‘Despite logging being off this is still logged’, force=True)

logging_on()

log(‘Do not add a new line after logging this string’, no_new_line=True)

log(‘. . . Some more’)

log(‘something’, prefix=’label:’)

will add to the log:

<nowiki># Add this string to the log</nowiki>

<nowiki># </nowiki>Despite logging being off this is still logged

<nowiki># Do not add a new line after logging this string# . . . Some more</nowiki>

<nowiki># </nowiki>label:something

===log_variable(var_name, label=’’)===

Description: Add to the log file a string describing the value of the specified variable.

Parameters: var_name'':'' Name of the variable to be logged.

prefix'':'' An optional label to add to the variable value instead of the variable name

Return: None

Example:

The following commands:

set(‘phone_number’, ‘111-234-5678’)

log_variable(‘phone_number’)

log_variable(‘phone_number’, label=’My phone number’)

will add to the log:

Variable 'phone_number' = 111-234-5678

My phone number = 111-234-5678

===log_server_info()===

Description: Add to the log file the server information including schema version supported obtained from the WMLS_GetVersion and server capabilities for all schema version supported obtained from WMLS_GetCap

Parameters: None

Return: None

Example:

The following commands:

log_server_info()

will add to the log something like:

Server schema versions supported:

1.3.1.1

Server capabilities for schema version 1.3.1.1:

<capServers xmlns:xsi="<nowiki>http://www.w3.org/2001/XMLSchema-instance</nowiki>" xmlns="<nowiki>http://www.witsml.org/api/131</nowiki>" xsi:schemaLocation="<nowiki>http://www.witsml.org/schemas/</nowiki>131 ..<nowiki>/obj_capServer.xs</nowiki>d" version="1.3.1">

<capServer apiVers="1.3.1">

&lt;contact&gt;

  . . .

&lt;/contact&gt;

. . .

&lt;description&gt;Pason DataHub Server&lt;/description&gt;

&lt;schemaVersion&gt;1.3.1.1&lt;/schemaVersion&gt;

&lt;function name="WMLS_GetVersion"/&gt;

&lt;function name="WMLS_GetBaseMsg"/&gt;

&lt;function name="WMLS_GetFromStore"&gt;

  &lt;dataObject&gt;well&lt;/dataObject&gt;

  . . .

&lt;/function&gt;

</capServer>

</capServers>

=Script Command Parameters=

The following are some of the script parameters used in the script commands above:

'''WMLtypeIn''': A string as defined in the WITSML schema. Constant values for this parameters are defined in ''<nowiki>witsml.py</nowiki> ''(e.g. WML_TYPE_IN_WELL)

'''XMLin, CapabilitiesIn, QueryIn''': A string containing an XML document

'''OptionsIn''': A Python dictionary containing option:value pairs (e.g. {dataVersion:”1.3.1.1”})

'''''''''ReturnValueIn''': A sting containing an integer value (e.g. ‘-101’)

'''expected_value_string, expected_value_substring, expected_xml_string''': A string to be compared with data received from the server

'''fail_string, success_string, print_string''': A string to be send to the output and logging file

'''xpath:''' A string specifying an element or attribute (based on the XPath specification)

'''script_name''': A string containing a file name of a Test Script

The following special constructs can be used in any of the script parameter strings:

'''$'''variable_name'''$ '''The construct is replaced with the variable contents at runtime

For example:

set (‘x’, ‘abc’)

check_XMLout_ElementValue(‘element’, ’$x$’)

Will check that the <element> is set to ‘abc’

'''@'''filename'''@''' The construct is replaced with the contents of the file specified

For example:

get_from_store(WML_TYPE_IN_WELL, “@<nowiki>get_all_wells.xm</nowiki>l@”)

Will send the query in the file ''<nowiki>get_all_wells.xm</nowiki>l''

^condition?str1:str2^ The construct is replaced with str1 if the condition is true or with ''str2'' otherwise

For example:

check_XMLout_ElementValue(‘element’, ‘^1==2?This:That^’)

Will check that the <element> is set to ‘That’

~<char> The construct is replaced with the character specified after the ‘~’. This is used to escape the special characters: '''''$'' ''@ ^ : &'''''

For example:

check_XMLout_ElementValue('element', '~$~&')

Will check that the <element> is set to ‘$&’

In addition the following special constructs can be used in any of the script parameter strings for the Verify Script commands (i.e. ''expected_value_string'', ''expected_value_substring'' and '' expected_xml_string'')

. The string will match any single character

.* The string will match any sequence of characters

&variable& The string will match any sequence of characters and save the matched string in the variable specified

For example:

check_XMLout_String(“.<well uid="&rx_uid&”/>.”)

Will check that a well object is received and save the received well uid in the variable ''rx_uid''

MongoDB Logo MongoDB