QTools  7.3.4
Collection of Host-Based Tools
Loading...
Searching...
No Matches
qutest_dsl Namespace Reference

Functions

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

Variables

int VERSION = 732
 current version of the Python QUTest interface
 

Function Documentation

◆ include()

qutest_dsl.include (   fname)

include python code in a test script

Description
This preamble 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 (see Example below).
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

Example
file to be included:

# file test_inc.pyi (include file)
# common on_reset() callback
def on_reset():
expect_pause()
glb_filter(GRP_ALL)
continue_test()
def my_test_snippet():
query_curr(OBJ_SM)
expect("@timestamp Query-SM Obj=Blinky::inst,State=Blinky::off")

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()
...

Definition at line 58 of file qutest_dsl.py.

◆ test_file()

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()

Definition at line 69 of file qutest_dsl.py.

◆ test_dir()

qutest_dsl.test_dir ( )

get the test directory (relative to the current directory)

Description
This complex command returns a string containing the directory name of the currently executed test script ("test group").
Usage
dir_name = test_dir()

Definition at line 80 of file qutest_dsl.py.

◆ test()

qutest_dsl.test (   title,
  opt = 0 
)

start a new test

Description
This complex 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 100 of file qutest_dsl.py.

◆ scenario()

qutest_dsl.scenario (   title,
  opt = 0 
)

start a new scenario

Description
This is an alias for the test() command for the BDD-style testing.

Definition at line 107 of file qutest_dsl.py.

◆ skip()

qutest_dsl.skip (   nTests = 9999)

skip the tests following this command.

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")
~ ~ ~
See also
test()

Definition at line 132 of file qutest_dsl.py.

◆ expect()

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 160 of file qutest_dsl.py.

◆ ensure()

qutest_dsl.ensure (   bool_expr)

ensures that the provided Boolean expression is true

Description
This command performs checking of a condition, which is believed to be true in order for a test to pass. If the provided Boolean expression evaluates to false, the test is failed in the usual way.
Parameters
[in]bool_exprthe Boolean expression to check
Usage
test("Ensure")
command("COMMAND_B", 123, 23456, 3456789)
expect("@timestamp COMMAND_B *")
last = last_rec().split()
p1 = int(last[2])
p2 = int(last[4])
ensure(123 == p1) # <---
ensure(3456789 == p2) # <---

Definition at line 174 of file qutest_dsl.py.

◆ glb_filter()

qutest_dsl.glb_filter ( args)

Send the QS Global Filter to the Target.

Description
This simple 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_SEM # Semaphore Record-Types (e.g., Semaphore take/signal)
GRP_MTX # Mutex Record-Types (e.g., Mutex 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
Returns
The 128-bit filter bitmask sent to the target. For each enabled filter with the QS record-ID recID the bitmask has a '1' in the position (1 << recID).
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
filters = glb_filter(GRP_AO, 78) # store the 128-bit bitmask returned
See also
loc_filter()

Definition at line 219 of file qutest_dsl.py.

◆ loc_filter()

qutest_dsl.loc_filter ( args)

Send the Local Filter to the Target.

Description
This simple 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)
Returns
The 128-bit filter bitmask sent to the target. For each enabled filter with the QS-ID qsID the bitmask has a '1' in the position (1 << qsID).
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
filters = loc_filter(IDS_AO, IDS_EP) # store the 128-bit bitmask returned
See also
glb_filter()

Definition at line 252 of file qutest_dsl.py.

◆ ao_filter()

qutest_dsl.ao_filter (   obj_id)

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

Description
This simple 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
See also
loc_filter()

Definition at line 276 of file qutest_dsl.py.

◆ current_obj()

qutest_dsl.current_obj (   obj_kind,
  obj_id 
)

Set the Current-Object in the Target.

Description
This simple 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
Parameters
[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)
See also

Definition at line 307 of file qutest_dsl.py.

◆ query_curr()

qutest_dsl.query_curr (   obj_kind)

query the current object in the Target

Description
This complex 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
OBJ_AO # Active Object object
OBJ_MP # Memory Pool object
OBJ_EQ # Event Queue object
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 345 of file qutest_dsl.py.

◆ tick()

qutest_dsl.tick (   tick_rate = 0)

trigger system clock tick in the Target

Description
This complex 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("...")
...
See also
current_obj()

Definition at line 365 of file qutest_dsl.py.

◆ expect_pause()

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")
continue_test()
expect_run()
See also
continue_test()

Definition at line 383 of file qutest_dsl.py.

◆ expect_run()

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():
expect_pause()
glb_filter(GRP_UA)
current_obj(OBJ_SM_AO, "AO_MyAO")
continue_test()
expect_run() # <====
See also
on_reset()

Definition at line 401 of file qutest_dsl.py.

◆ continue_test()

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():
expect_pause()
glb_filter(GRP_UA)
current_obj(OBJ_SM_AO, "AO_MyAO")
continue_test() # <====
expect_run()
See also
expect_pause()

Definition at line 414 of file qutest_dsl.py.

◆ command()

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

executes a given command in the Target

Description
This complex command causes execution of the QS_onCommand() callback in the test fixture.
Parameters
[in]cmdIdthe first cmdId argument for the QS_onCommand() callback function in the test fixture.
Note
The cmdId parameter could be either the raw number or a name that is delivered by QS_ENUM_DICTIONARY(enum, group), where the second group argument is QS_CMD (numerical value 7).
Parameters
[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("...")
... # output generated by this command
expect("@timestamp Trg-Done QS_RX_COMMAND")
command("MY_CMD", 123, 456, 789) # <===
... # output generated by this command
expect("@timestamp Trg-Done QS_RX_COMMAND")

Definition at line 436 of file qutest_dsl.py.

◆ init()

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()
init("MY_SIG")
init("MY_SIG", pack("<B", 2))

Definition at line 455 of file qutest_dsl.py.

◆ dispatch()

qutest_dsl.dispatch (   signal,
  params = None 
)

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

Description
This complex 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))

Definition at line 472 of file qutest_dsl.py.

◆ post()

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))

Definition at line 489 of file qutest_dsl.py.

◆ publish()

qutest_dsl.publish (   signal,
  params = None 
)

publish a given event to subscribers in the Target

Description
This complex 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))

Definition at line 506 of file qutest_dsl.py.

◆ probe()

qutest_dsl.probe (   func,
  data 
)

sends a Test-Probe to the Target

Description
This simple 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)

Definition at line 532 of file qutest_dsl.py.

◆ peek()

qutest_dsl.peek (   offset,
  size,
  num 
)

peeks data in the Target

Description
This complex 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)

Definition at line 551 of file qutest_dsl.py.

◆ poke()

qutest_dsl.poke (   offset,
  size,
  data 
)

pokes data into the Target.

Description
This simple 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"))

Definition at line 570 of file qutest_dsl.py.

◆ fill()

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

fills data into the Target.

Description
This simple 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)

Definition at line 589 of file qutest_dsl.py.

◆ note()

qutest_dsl.note (   msg,
  dest = (SCREEN | TRACE) 
)

display a note in the QUTest output and in QSPY output.

Description
This command allows the test script to output a note (text) both to the QUTest output (text/log) and the QSPY output (text/log). This command can be also used for commenting the test scripts.
Parameters
[in]msgtext message
[in]destdestination (SCREEN, TRACE), default both
Usage
note("This is a short note")
note('''
This test group checks the MPU (Memory Protection Unit)
by reading/writing from/to various memory addresses
in the target
''', SCREEN)

Definition at line 610 of file qutest_dsl.py.

◆ tag()

qutest_dsl.tag (   msg,
  dest = (SCREEN | TRACE) 
)

display a tag in the QUTest output and in QSPY output.

Description
This is an alias for the note() command for the BDD-style testing.

Definition at line 617 of file qutest_dsl.py.

◆ pack()

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](https://docs.python.org/3/library/struct.html#format-strings") exactly. The pack() command is typically used inside other QUTest commands to pack the binary event parameters or binary data for poke() and fill(). @param [in] format string @param [in] v1 one or more data elements requried by format @param [in] v2 one or more data elements requried by format @par Usage @code{py} dispatch("MY_SIG", pack("<B", 2)) poke(2, 2, pack("<HH", 0xB2C2, 0xD2E2))

Definition at line 640 of file qutest_dsl.py.

◆ last_rec()

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)

Definition at line 657 of file qutest_dsl.py.

◆ on_reset()

qutest_dsl.on_reset ( )

callback function invoked after each Target reset

Definition at line 661 of file qutest_dsl.py.

◆ on_setup()

qutest_dsl.on_setup ( )

callback function invoked at the beginning of each test

Definition at line 665 of file qutest_dsl.py.

◆ on_teardown()

qutest_dsl.on_teardown ( )

callback function invoked at the end of each test

Definition at line 669 of file qutest_dsl.py.

Variable Documentation

◆ VERSION

int qutest_dsl.VERSION = 732

current version of the Python QUTest interface

Definition at line 33 of file qutest_dsl.py.