QTools  6.9.4
Collection of Host-Based Tools
qutest_dsl Namespace Reference

Functions

def include (fname)
 include python code in a test script More...
 
def test_file ()
 get the test file name with path More...
 
def test_dir ()
 get the test directory (relative to the current directory) More...
 
def test (title, opt=0)
 start a new test More...
 
def skip (nTests=9999)
 skip the tests following this command. More...
 
def expect (match)
 defines an expectation for the current test More...
 
def glb_filter (*args)
 Send the QS Global Filter to the Target. More...
 
def loc_filter (*args)
 Send the Local Filter to the Target. More...
 
def ao_filter (obj_id)
 Updates the Local Filter for a given AO in the Target. More...
 
def current_obj (obj_kind, obj_id)
 Set the Current-Object in the Target. More...
 
def query_curr (obj_kind)
 query the current object in the Target More...
 
def tick (tick_rate=0)
 trigger system clock tick in the Target More...
 
def expect_pause ()
 defines expectation for a Test Pause More...
 
def expect_run ()
 defines expectation for calling QF_run()/QF::run() More...
 
def continue_test ()
 sends the CONTINUE packet to the Target to continue a test More...
 
def command (cmdId, param1=0, param2=0, param3=0)
 executes a given command in the Target More...
 
def init (signal=0, params=None)
 take the top-most initial transition in the current SM object in the Target More...
 
def dispatch (signal, params=None)
 dispatch a given event in the current SM object in the Target More...
 
def post (signal, params=None)
 post a given event to the current AO object in the Target More...
 
def publish (signal, params=None)
 publish a given event to subscribers in the Target More...
 
def probe (func, data)
 sends a Test-Probe to the Target More...
 
def peek (offset, size, num)
 peeks data in the Target More...
 
def poke (offset, size, data)
 pokes data into the Target. More...
 
def fill (offset, size, num, item=0)
 fills data into the Target. More...
 
def pack (format, v1, v2)
 packs data into binary string to be sent to QSPY. More...
 
def last_rec ()
 returns last record received from the target as string. More...
 
def on_reset ()
 callback function invoked after each Target reset More...
 
def on_setup ()
 callback function invoked at the beginning of each test More...
 
def on_teardown ()
 callback function invoked at the end of each test More...
 

Variables

int VERSION = 694
 current version of the Python QUTest interface More...
 

Function Documentation

◆ include()

def qutest_dsl.include (   fname)

include python code in a test script

Description
This command includes python code in a specified file into the test script. The included file can contain any code that you would put into test scripts, such as
Parameters
[in]fnamename of the file to include. May contain a path relative to the test script.
Usage
include("test_include.pyi") # file in the same directory as the script
~ ~ ~
include("../my_include/test_include.pyi") # relative directory
def include(fname)
include python code in a test script
Definition: qutest_dsl.py:79

Example
file to be included:

# file test_inc.pyi (include file)
# common on_reset() callback
def on_reset():
glb_filter(GRP_ALL)
def my_test_snippet():
query_curr(OBJ_SM)
expect("@timestamp Query-SM Obj=Blinky::inst,State=Blinky::off")
def expect(match)
defines an expectation for the current test
Definition: qutest_dsl.py:174
def expect_pause()
defines expectation for a Test Pause
Definition: qutest_dsl.py:363
def glb_filter(*args)
Send the QS Global Filter to the Target.
Definition: qutest_dsl.py:212
def continue_test()
sends the CONTINUE packet to the Target to continue a test
Definition: qutest_dsl.py:394
def query_curr(obj_kind)
query the current object in the Target
Definition: qutest_dsl.py:326
def on_reset()
callback function invoked after each Target reset
Definition: qutest_dsl.py:605

test script calling include():

# file test_blinky.py (actual test script)
include("test_inc.pyi") #<--- include common code
test("my test xyz")
my_test_snippet()
...
def test(title, opt=0)
start a new test
Definition: qutest_dsl.py:120

Definition at line 79 of file qutest_dsl.py.

◆ test_file()

def qutest_dsl.test_file ( )

get the test file name with path

Description
This command returns a string containing the file name of the currently executed test script ("test group").
Usage
file_name = test_file()
def test_file()
get the test file name with path
Definition: qutest_dsl.py:90

Definition at line 90 of file qutest_dsl.py.

◆ test_dir()

def qutest_dsl.test_dir ( )

get the test directory (relative to the current directory)

Description
This command returns a string containing the directory name of the currently executed test script ("test group").
Usage
dir_name = test_dir()
def test_dir()
get the test directory (relative to the current directory)
Definition: qutest_dsl.py:101

Definition at line 101 of file qutest_dsl.py.

◆ test()

def qutest_dsl.test (   title,
  opt = 0 
)

start a new test

Description
This command starts a new test and gives it a name.
Parameters
[in]titletitle of the test
[in]optoptions {0=default, NORESET}
Usage
test("my first test") # test with title and with full target reset
~ ~ ~
test("my second test", NORESET) # test without target reset
~ ~ ~
See also
skip()

Definition at line 120 of file qutest_dsl.py.

◆ skip()

def qutest_dsl.skip (   nTests = 9999)

skip the tests following this command.

Description
Parameters
[in]nTestsnumber of tests to skip (default-all remaining tests) e.g., skip(1) will skip one test following this command.
Note
The skipped tests are not executed, but they are checked for syntax errors, such as commands and parameters coded in the skipped tests.
Usage
test("my first test")
~ ~ ~
skip(1) # skip one subsequent test
test("my second test")
~ ~ ~
skip() # skip all subsequent tests
test("my second test")
~ ~ ~
def skip(nTests=9999)
skip the tests following this command.
Definition: qutest_dsl.py:146
See also
test()

Definition at line 146 of file qutest_dsl.py.

◆ expect()

def qutest_dsl.expect (   match)

defines an expectation for the current test

Description
This command defines a new expecation for the textual output produced by QSPY.
Parameters
[in]matchthe expected match for the QSPY output The match string can contain special characters, such as: *, ? and [chars], which are matched according to the Python command fnmatch.fnmatchcase()
Note
The match string can be the printf-style %-subsitution string (compatible with Python 2 and Python 3), or the new "f-string" (compatible only with Python 3).
The special string "@timestamp" (or "%timestamp") at the beginning of the match parameter will be automatically replaced with the current numerical value of the test sequence-counter.
Usage
expect("0000000001 USER+000 FindFunction_WhichIsBroken 0 78")
expect("@timestamp Trg-Done QS_RX_COMMAND")
expect(" Tick<0> Ctr=*")
expect("@timestamp IO_CALL IO_Write %d %d" %(CommandReg, ProgramCmd))

Definition at line 174 of file qutest_dsl.py.

◆ glb_filter()

def qutest_dsl.glb_filter ( args)

Send the QS Global Filter to the Target.

Description
This command sends the complete QS Global Filter to the Target. Any existing Global Filter setting inside the Target will be overwritten.
Parameters
[in]argslist of Record-Type groups or individual Record-Types to set or clear. A given filter-group or an individual filter is set when it is positive, and cleared with it is preceded with the minus (-) sign.


The filter list can contain the following:

GRP_ALL # all Record-Types
GRP_SM # State Machine Record-Types
GRP_AO # Active Object Record-Types
GRP_MP # Memory Pool Record-Types
GRP_EQ # Event Queue Record-Types
GRP_TE # Time Events Record-Types
GRP_QF # Framework Record-Types (e.g., post/publish/..)
GRP_SC # Scheduler Record-Types (e.g., scheduler lock/unlock)
GRP_U0 # User group 0 (Record-Types 100-104)
GRP_U1 # User group 1 (Record-Types 105-109)
GRP_U2 # User group 2 (Record-Types 110-114)
GRP_U3 # User group 3 (Record-Types 115-119)
GRP_U4 # User group 0 (Record-Types 120-124)
GRP_UA # All user records (Record-Types 100-124)
<num> # Specific QS trace Record-Type in the range 0..127
Usage
glb_filter() # clears all global filters
glb_filter(GRP_ALL) # sets all global filters
glb_filter(GRP_SM, GRP_AO) # sets SM-group and AO-group
glb_filter(GRP_ALL, -GRP_SC) # sets all global filters, but clears the SC-group
glb_filter(GRP_QF, "-QS_QF_TICK") # sets the QF-group, but clears the QS_QF_TICK filter
glb_filter(GRP_AO, 78)` # sets the AO-group and the QS record 78
See also
loc_filter()

Definition at line 212 of file qutest_dsl.py.

◆ loc_filter()

def qutest_dsl.loc_filter ( args)

Send the Local Filter to the Target.

Description
This command sends the complete QS Local Filter to the Target. Any existing Local Filter setting inside the Target will be overwritten.
Parameters
[in]argslist of QS-ID groups or individual QS-IDs to set or clear. A given filter-group or an individual filter is set when it is positive, and cleared with it is preceded with the minus (-) sign.
This parameter can take one of the following values:
IDS_ALL # all QS-IDs
IDS_AO # Active Object QS-IDs (1..64)
IDS_EP # Event Pool QS-IDs (65-80)
IDS_EQ # Event Queue QS-IDs (81-96)
IDS_AP # Application-Specific QS-IDs (97-127)
Usage
loc_filter(IDS_ALL) # enables all QS-IDs
loc_filter(-IDS_ALL) # disables all QS-IDs
loc_filter(IDS_AO) # enables all active objcts
loc_filter(IDS_AO, -6) # enables all active objcts,
# but disables AO with priority 6
loc_filter(IDS_AO, IDS_EP) # enables all active objects and event pools
loc_filter(IDS_AP) # enables all app-specific QS_IDs
def loc_filter(*args)
Send the Local Filter to the Target.
Definition: qutest_dsl.py:239
See also
glb_filter()

Definition at line 239 of file qutest_dsl.py.

◆ ao_filter()

def qutest_dsl.ao_filter (   obj_id)

Updates the Local Filter for a given AO in the Target.

Description
This command sets or clears the QS Local Filter corresponding to the given AO in the Target. Unlike loc_filter(), this facility changes only the QS-ID (AO's priority) of the given AO in the Target. All other Local Filters will be left unchanged.
Parameters
[in]obj_idactive object to set/clear the local filter for in the Target
This parameter can be either a string (name of the AO) or the AO's priority. Also, it can be either positive (to set) or negative (to clear) the QS local filter.
Usage
ao_filter(6) # enables AO of priority 6 in the Target
ao_filter(-6) # disables AO of priority 6 in the Target
ao_filter("AO_Table") # enables "AO_Table" in the Target
ao_filter("-AO_Table") # disables "AO_Table" in the Target
def ao_filter(obj_id)
Updates the Local Filter for a given AO in the Target.
Definition: qutest_dsl.py:259
See also
loc_filter()

Definition at line 259 of file qutest_dsl.py.

◆ current_obj()

def qutest_dsl.current_obj (   obj_kind,
  obj_id 
)

Set the Current-Object in the Target.

Description
This command sets the "current object" in the Target.
Parameters
[in]obj_kindKind of object to set
This parameter can take one of the following values:
OBJ_SM # State Machine object
OBJ_AO # Active Object object
OBJ_MP # Memory Pool object
OBJ_EQ # Event Queue object
OBJ_TE # Time Event object
OBJ_AP # Application-Specific object
OBJ_SM_AO # Both, State Machine and Active Object
[in]obj_idName or addres of the object
Usage
current_obj(OBJ_SM, "my_state_machine")
current_obj(OBJ_MP, "EvtPool1")
current_obj(OBJ_AP, "my_object")
current_obj(OBJ_SM_AO, "Philo[2]")
current_obj(OBJ_AP, 0x20001234)
def current_obj(obj_kind, obj_id)
Set the Current-Object in the Target.
Definition: qutest_dsl.py:289
See also

Definition at line 289 of file qutest_dsl.py.

◆ query_curr()

def qutest_dsl.query_curr (   obj_kind)

query the current object in the Target

Description
This command queries the current object in the Target.
Parameters
[in]obj_kindKind of object to query
This parameter can take one of the following values:
OBJ_SM # State Machine object@n
OBJ_AO # Active Object object@n
OBJ_MP # Memory Pool object@n
OBJ_EQ # Event Queue object@n
OBJ_TE # Time Event object
Usage
The queries for various objects generate the following QS trace records from the Target
query_curr(OBJ_SM)
"@timestamp Query-SM Obj=<obj-name>,State=<state-name>"
query_curr(OBJ_AO)
"@timestamp Query-AO Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
query_curr(OBJ_EQ)
"@timestamp Query-EQ Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
query_curr(OBJ_MP)
"@timestamp Query-MP Obj=<obj-name>,Free=<n>,Min=<m>"
query_curr(OBJ_TE)
"@timestamp Query-TE Obj=<obj-name>,Rate=<r>,Sig=<s>,Tim=<n>,Int=<m>,Flags=<f>"
See also
current_obj()

Definition at line 326 of file qutest_dsl.py.

◆ tick()

def qutest_dsl.tick (   tick_rate = 0)

trigger system clock tick in the Target

Description
This command triggers the following actions in the Target:
  1. If the current TE object is defined and the TE is armed, the TE is disarmed (if one-shot) and then posted to the recipient AO.
  2. The linked-list of all armed Time Events is updated.
Parameters
[in]tick_ratethe tick rate (0..QF_MAX_TICK_RATE)
Usage
# tests...
test("tick")
glb_filter(GRP_ALL)
current_obj(OBJ_TE, "l_philo<2>.timeEvt")
tick() # <====
expect("...")
...
def tick(tick_rate=0)
trigger system clock tick in the Target
Definition: qutest_dsl.py:345
See also
current_obj()

Definition at line 345 of file qutest_dsl.py.

◆ expect_pause()

def qutest_dsl.expect_pause ( )

defines expectation for a Test Pause

Description
This is a special expectation that must match the macro QS_TEST_PAUSE() inside the test fixture.
Note
If QS_TEST_PAUSE() is called before QF_run(), the expect_pause() expectation must be placed in the on_reset() callback.
Usage
def on_reset():
expect_pause() # <====
glb_filter(GRP_UA)
current_obj(OBJ_SM_AO, "AO_MyAO")
def expect_run()
defines expectation for calling QF_run()/QF::run()
Definition: qutest_dsl.py:381
See also
continue_test()

Definition at line 363 of file qutest_dsl.py.

◆ expect_run()

def qutest_dsl.expect_run ( )

defines expectation for calling QF_run()/QF::run()

Description
This is a special expectation for the target calling the QF_run()/QF::run() function.
Note
This expectation must be placed at the right place in the on_reset() callback.
Usage
def on_reset():
glb_filter(GRP_UA)
current_obj(OBJ_SM_AO, "AO_MyAO")
expect_run() # <====
See also
on_reset()

Definition at line 381 of file qutest_dsl.py.

◆ continue_test()

def qutest_dsl.continue_test ( )

sends the CONTINUE packet to the Target to continue a test

Description
This command continues the test after QS_TEST_PAUSE().
Usage
def on_reset():
glb_filter(GRP_UA)
current_obj(OBJ_SM_AO, "AO_MyAO")
continue_test() # <====
See also
expect_pause()

Definition at line 394 of file qutest_dsl.py.

◆ command()

def qutest_dsl.command (   cmdId,
  param1 = 0,
  param2 = 0,
  param3 = 0 
)

executes a given command in the Target

Description
This command causes execution of the callback QS_onCommand() inside the the Target system.
Parameters
[in]cmdIdthe command-id first argument to QS_onCommand()
NOTE: this could be either the raw number or a name that is delivered by QS_USR_DICTIONARY() from the Target
[in]param1the "param1" argument to QS_onCommand() (optional)
[in]param2the "param2" argument to QS_onCommand() (optional)
[in]param3the "param3" argument to QS_onCommand() (optional)
Usage
test("...")
...
command(0, 78) # <===
expect("...")
...
def command(cmdId, param1=0, param2=0, param3=0)
executes a given command in the Target
Definition: qutest_dsl.py:411

Definition at line 411 of file qutest_dsl.py.

◆ init()

def qutest_dsl.init (   signal = 0,
  params = None 
)

take the top-most initial transition in the current SM object in the Target

Description
This command takes the top-most initial transition in the current SM object in the Target.
Parameters
[in]signalthe event signal of the "initialization event"
[in]paramsthe parameters of the "initialization event"
Usage
init("MY_SIG")
init("MY_SIG", pack("<B", 2))
def pack(format, v1, v2)
packs data into binary string to be sent to QSPY.
Definition: qutest_dsl.py:584
def init(signal=0, params=None)
take the top-most initial transition in the current SM object in the Target
Definition: qutest_dsl.py:430

Definition at line 430 of file qutest_dsl.py.

◆ dispatch()

def qutest_dsl.dispatch (   signal,
  params = None 
)

dispatch a given event in the current SM object in the Target

Description
This command dispatches a given event in the current SM object in the Target.
Parameters
[in]signalthe event signal of the event to be dispatched
[in]paramsthe parameters of the event to be dispatched
Usage
dispatch("MY_SIG")
dispatch("MY_SIG", pack("<B", 2))
def dispatch(signal, params=None)
dispatch a given event in the current SM object in the Target
Definition: qutest_dsl.py:447

Definition at line 447 of file qutest_dsl.py.

◆ post()

def qutest_dsl.post (   signal,
  params = None 
)

post a given event to the current AO object in the Target

Description
This command posts a given event to the current AO object in the Target.
Parameters
[in]signalthe event signal of the event to be posted
[in]paramsthe parameters of the event to be posted
Usage
`post("MY_SIG")
`post("MY_SIG", pack("<B", 2))
def post(signal, params=None)
post a given event to the current AO object in the Target
Definition: qutest_dsl.py:464

Definition at line 464 of file qutest_dsl.py.

◆ publish()

def qutest_dsl.publish (   signal,
  params = None 
)

publish a given event to subscribers in the Target

Description
This command publishes a given event in the Target.
Parameters
[in]signalthe event signal of the event to be posted
[in]paramsthe parameters of the event to be posted
Usage
publish("MY_SIG")
publish("MY_SIG", pack("<B", 2))
def publish(signal, params=None)
publish a given event to subscribers in the Target
Definition: qutest_dsl.py:480

Definition at line 480 of file qutest_dsl.py.

◆ probe()

def qutest_dsl.probe (   func,
  data 
)

sends a Test-Probe to the Target

Description
This command sends the Test Probe data to the Target. The Target collects these Test Probes preserving the order in which they were sent. Subsequently, whenever a given API is called inside the Target, it can obtain the Test-Probe by means of the QS_TEST_PROBE_DEF() macro. The QS_TEST_PROBE_DEF() macro returns the Test-Probes in the same order as they were received to the Target. If there are no more Test- Probes for a given API, the Test-Probe is initialized to zero.
Parameters
[in]functhe name or raw address of a function
[in]datathe data (uint32_t) for the Test-Probe
Note
All Test-Probes are cleared when the Target resets and also upon the start of a new test, even if this test does not reset the Target (NORESET tests).
Usage
probe("myFunction", 123)
def probe(func, data)
sends a Test-Probe to the Target
Definition: qutest_dsl.py:505

Definition at line 505 of file qutest_dsl.py.

◆ peek()

def qutest_dsl.peek (   offset,
  size,
  num 
)

peeks data in the Target

Description
This command peeks data at the given offset from the start address of the current_obj() inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]sizesize of the data items (1, 2, or 4)
[in]numnumber of data items to peek
Usage
peek(0, 1, 10)
peek(8, 2, 4)
peek(4, 4, 2)
def peek(offset, size, num)
peeks data in the Target
Definition: qutest_dsl.py:524

Definition at line 524 of file qutest_dsl.py.

◆ poke()

def qutest_dsl.poke (   offset,
  size,
  data 
)

pokes data into the Target.

Description
This command pokes provided data at the given offset from the start address of the current AP object inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]sizesize of the data items (1, 2, or 4)
[in]databinary data to send
Usage
poke(4,4,pack("<II",0xB4C4D4E4,0xB5C5D5E5))
poke(0, 1, bytearray("dec=%d\0", "ascii"))
poke(0, 1, bytes("Hello World!\0","ascii"))
def poke(offset, size, data)
pokes data into the Target.
Definition: qutest_dsl.py:542

Definition at line 542 of file qutest_dsl.py.

◆ fill()

def qutest_dsl.fill (   offset,
  size,
  num,
  item = 0 
)

fills data into the Target.

Description
This command fills provided data at the given offset from the start address of the current_obj() inside the Target.
Parameters
[in]offsetoffset [in bytes] from the start of the current_obj()
[in]sizesize of the data item (1, 2, or 4)
[in]numnumber of data items to fill
[in]itemdata item to fill with
Usage
fill(0, 1, 100, 0x1A)
fill(0, 2, 50, 0x2A2B)
fill(0, 4, 25, 0x4A4B4C4D)
def fill(offset, size, num, item=0)
fills data into the Target.
Definition: qutest_dsl.py:561

Definition at line 561 of file qutest_dsl.py.

◆ pack()

def qutest_dsl.pack (   format,
  v1,
  v2 
)

packs data into binary string to be sent to QSPY.

Description
This command corresponds to Python struct.pack(). It returns a bytes object containing the values v1, v2,... packed according to the format string format. The arguments must match the values required by the format exactly. The pack() command is typically used inside other QUTest commands to pack the binary event parameters or binary data for poke() and fill().
Parameters
[in]formatstring
[in]v1one or more data elements requried by format
[in]v2one or more data elements requried by format
Usage
dispatch("MY_SIG", pack("<B", 2))
poke(2, 2, pack("<HH", 0xB2C2, 0xD2E2))

Definition at line 584 of file qutest_dsl.py.

◆ last_rec()

def qutest_dsl.last_rec ( )

returns last record received from the target as string.

Usage
command("COMMAND_B", 123, 23456, 3456789) # generate record (if needed)
expect("@timestamp COMMAND_B *") # expect the record from the target
last = last_rec().split() # <-- obtain the last record and split it
p1 = int(last[2]) # extract the expected parameter p1 (int)
s1 = last[3] # extract the expected string s1
p2 = int(last[4]) # extract the expected parameter p2 (int)
s2 = last[5] # extract the expected string s2
p3 = int(last[6]) # extract the expected parameter p3 (int)
p4 = float(last[7]) # extract the expected parameter p4 (float)
def last_rec()
returns last record received from the target as string.
Definition: qutest_dsl.py:601

Definition at line 601 of file qutest_dsl.py.

◆ on_reset()

def qutest_dsl.on_reset ( )

callback function invoked after each Target reset

Definition at line 605 of file qutest_dsl.py.

◆ on_setup()

def qutest_dsl.on_setup ( )

callback function invoked at the beginning of each test

Definition at line 609 of file qutest_dsl.py.

◆ on_teardown()

def qutest_dsl.on_teardown ( )

callback function invoked at the end of each test

Definition at line 613 of file qutest_dsl.py.

Variable Documentation

◆ VERSION

int VERSION = 694

current version of the Python QUTest interface

Definition at line 54 of file qutest_dsl.py.