Functions
def	include (fname)
	include python code in a test script

def	test_file ()
	get the test file name with path

def	test_dir ()
	get the test directory (relative to the current directory)

def	test (title, opt=0)
	start a new test

def	scenario (title, opt=0)
	start a new scenario

def	skip (nTests=9999)
	skip the tests following this command.

def	expect (match)
	defines an expectation for the current test

def	ensure (bool_expr)
	ensures that the provided Boolean expression is true

def	glb_filter (*args)
	Send the QS Global Filter to the Target.

def	loc_filter (*args)
	Send the Local Filter to the Target.

def	ao_filter (obj_id)
	Updates the Local Filter for a given AO in the Target.

def	current_obj (obj_kind, obj_id)
	Set the Current-Object in the Target.

def	query_curr (obj_kind)
	query the current object in the Target

def	tick (tick_rate=0)
	trigger system clock tick in the Target

def	expect_pause ()
	defines expectation for a Test Pause

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

def	continue_test ()
	sends the CONTINUE packet to the Target to continue a test

def	command (cmdId, param1=0, param2=0, param3=0)
	executes a given command in the Target

def	init (signal=0, params=None)
	take the top-most initial transition in the current SM object in the Target

def	dispatch (signal, params=None)
	dispatch a given event in the current SM object in the Target

def	post (signal, params=None)
	post a given event to the current AO object in the Target

def	publish (signal, params=None)
	publish a given event to subscribers in the Target

def	probe (func, data)
	sends a Test-Probe to the Target

def	peek (offset, size, num)
	peeks data in the Target

def	poke (offset, size, data)
	pokes data into the Target.

def	fill (offset, size, num, item=0)
	fills data into the Target.

def	note (msg, dest=(SCREEN\|TRACE))
	display a note in the QUTest output and in QSPY output.

def	tag (msg, dest=(SCREEN\|TRACE))
	display a tag in the QUTest output and in QSPY output.

def	pack (format, v1, v2)
	packs data into binary string to be sent to QSPY.

def	last_rec ()
	returns last record received from the target as string.

def	on_reset ()
	callback function invoked after each Target reset

def	on_setup ()
	callback function invoked at the beginning of each test

def	on_teardown ()
	callback function invoked at the end of each test

Variables
int	VERSION = 721
	current version of the Python QUTest interface

Function Documentation

◆ include()

def include ( fname )

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] fname name 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()

def test_file ( )

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

def test_dir ( )

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

def test	(	title,
		opt = `0`
	)

Description: This complex command starts a new test and gives it a name.

Parameters

[in]	title	title of the test
[in]	opt	options {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()

def scenario	(	title,
		opt = `0`
	)

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

Definition at line 107 of file qutest_dsl.py.

◆ skip()

def skip ( nTests = 9999 )

Parameters

[in] nTests number 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()

def expect ( match )

Description: This command defines a new expecation for the textual output produced by QSPY.

Parameters

[in] match the 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()

def ensure ( bool_expr )

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

def glb_filter ( * args )

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]

args

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

def loc_filter ( * args )

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] args list 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()

def ao_filter ( obj_id )

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

def current_obj	(	obj_kind,
		obj_id
	)

Description: This simple command sets the "current object" in the Target.

Parameters

[in] obj_kind Kind 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_id Name 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()

def query_curr ( obj_kind )

Description: This complex command queries the current object in the Target.

Parameters

[in] obj_kind Kind 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()

def tick ( tick_rate = 0 )

Description

This complex command triggers the following actions in the Target:

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.
The linked-list of all armed Time Events is updated.

Parameters

[in] tick_rate the 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()

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

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

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

def command	(	cmdId,
		param1 = `0`,
		param2 = `0`,
		param3 = `0`
	)

Description: This complex command causes execution of the QS_onCommand() callback in the test fixture.

Parameters

[in] cmdId the 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]	param1	the "param1" argument to `QS_onCommand()` (optional)
[in]	param2	the "param2" argument to `QS_onCommand()` (optional)
[in]	param3	the "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()

def init	(	signal = `0`,
		params = `None`
	)

Description: This command takes the top-most initial transition in the current SM object in the Target.

Parameters

[in]	signal	the event signal of the "initialization event"
[in]	params	the 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()

def dispatch	(	signal,
		params = `None`
	)

Description: This complex command dispatches a given event in the current SM object in the Target.

Parameters

[in]	signal	the event signal of the event to be dispatched
[in]	params	the 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()

def post	(	signal,
		params = `None`
	)

Description: This command posts a given event to the current AO object in the Target.

Parameters

[in]	signal	the event signal of the event to be posted
[in]	params	the 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()

def publish	(	signal,
		params = `None`
	)

Description: This complex command publishes a given event in the Target.

Parameters

[in]	signal	the event signal of the event to be posted
[in]	params	the 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()

def probe	(	func,
		data
	)

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]	func	the name or raw address of a function
[in]	data	the 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()

def peek	(	offset,
		size,
		num
	)

Description: This complex command peeks data at the given offset from the start address of the current_obj() inside the Target.

Parameters

[in]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data items (1, 2, or 4)
[in]	num	number 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()

def poke	(	offset,
		size,
		data
	)

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]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data items (1, 2, or 4)
[in]	data	binary 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()

def fill	(	offset,
		size,
		num,
		item = `0`
	)

Description: This simple command fills provided data at the given offset from the start address of the current_obj() inside the Target.

Parameters

[in]	offset	offset [in bytes] from the start of the current_obj()
[in]	size	size of the data item (1, 2, or 4)
[in]	num	number of data items to fill
[in]	item	data 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()

def note	(	msg,
		dest = `(SCREEN \| TRACE)`
	)

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]	msg	text message
[in]	dest	destination (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()

def tag	(	msg,
		dest = `(SCREEN \| TRACE)`
	)

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

Definition at line 617 of file qutest_dsl.py.

◆ pack()

def pack	(	format,
		v1,
		v2
	)

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

def last_rec ( )

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

def on_reset ( )

Definition at line 661 of file qutest_dsl.py.

◆ on_setup()

def on_setup ( )

Definition at line 665 of file qutest_dsl.py.

◆ on_teardown()

def on_teardown ( )

Definition at line 669 of file qutest_dsl.py.

Variable Documentation

◆ VERSION

int VERSION = 721

Definition at line 33 of file qutest_dsl.py.

Functions

Variables

Function Documentation

◆ include()

◆ test_file()

◆ test_dir()

◆ test()

◆ scenario()

◆ skip()

◆ expect()

◆ ensure()

◆ glb_filter()

◆ loc_filter()

◆ ao_filter()

◆ current_obj()

◆ query_curr()

◆ tick()

◆ expect_pause()

◆ expect_run()

◆ continue_test()

◆ command()

◆ init()

◆ dispatch()

◆ post()

◆ publish()

◆ probe()

◆ peek()

◆ poke()

◆ fill()

◆ note()

◆ tag()

◆ pack()

◆ last_rec()

◆ on_reset()

◆ on_setup()

◆ on_teardown()

Variable Documentation

◆ VERSION