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
	skip (nTests=9999)
	skip the tests following this command.
	SCENARIO (self, title="", opt=0)
	start a new BDD-style scenario (alternative #1)
	GIVEN (self, msg="", dest=0x3)
	start the "given" section of a BDD-style scenario (alternative #1)
	WHEN (self, msg="", dest=0x3)
	start the "when" section of a BDD-style scenario (alternative #1)
	THEN (self, msg="", dest=0x3)
	start the "then" section of a BDD-style scenario (alternative #1)
	AND (self, msg="", dest=0x3)
	adds the "and" section of a BDD-style scenario (alternative #1)
	scenario (title, opt=0)
	start a new BDD-style scenario (alternative #2)
	given (given_msg, and_msg)
	start the "given" section of a BDD-style scenario (alternative #2)
	when (given_msg, and_msg)
	start the "when" section of a BDD-style scenario (alternative #2)
	then (given_msg, and_msg)
	start the "then" section of a BDD-style scenario (alternative #2)
	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 = 740
	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]

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 56 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 68 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]	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() @scenario()

Definition at line 101 of file qutest_dsl.py.

skip()

qutest_dsl.skip

(

nTests = 9999

)

skip the tests following this command.

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

SCENARIO()

qutest_dsl.SCENARIO	(		self,
			title = "",
			opt = 0 )

start a new BDD-style scenario (alternative #1)

Description
This function that starts a new BDD-style scenario.

Parameters

[in]	title	title of the scenario
[in]	opt	options {0=default, NORESET}

The SCENARIO() command outputs the provided title (text) to the QUTest output (text/log) and the QSPY output (text/log), adding the prefix

Usage

SCENARIO("extened->basic->extended") # <=====
GIVEN("basic thread priorities: 4,0,0")
. . .
AND("extended thread priorities: 1,5,0")
. . .
 
WHEN("post TEST0_SIG->thrX[0]")
. . .
THEN("Extpect the following preemptions")
. . .

See also

• GIVEN()
• WHEN()
• THEN()
• AND()

Definition at line 159 of file qutest_dsl.py.

GIVEN()

qutest_dsl.GIVEN	(		self,
			msg = "",
			dest = 0x3 )

start the "given" section of a BDD-style scenario (alternative #1)

Description
This function defines the "given" section of a BDD-scenario. The GIVEN() section typically sets up the context for the "given-when-then" sequence. Therefore, a GIVEN() section should follow SCENARIO().

Parameters

[in]	msg	optional "given" message
[in]	dest	optional destination of the message (both screen and QSPY)

Usage

SCENARIO("extened->basic->extended")
GIVEN("basic thread priorities: 4,0,0") # <=====
. . .
AND("extended thread priorities: 1,5,0")
. . .
 
WHEN("post TEST0_SIG->thrX[0]")
. . .
THEN("Extpect the following preemptions")
. . .

See also

• SCENARIO()
• WHEN()
• THEN()
• AND()

Definition at line 192 of file qutest_dsl.py.

WHEN()

qutest_dsl.WHEN	(		self,
			msg = "",
			dest = 0x3 )

start the "when" section of a BDD-style scenario (alternative #1)

Description
This function that defines the "when" section of a BDD-scenario. The commands in this section typically include the command() or post() command. The WHEN() section should follow the GIVEN() section.

Parameters

[in]	msg	optional "when" message
[in]	dest	optional destination of the message (both screen and QSPY)

Usage

SCENARIO("extened->basic->extended")
GIVEN("basic thread priorities: 4,0,0")
. . .
AND("extended thread priorities: 1,5,0")
. . .
 
WHEN("post TEST0_SIG->thrX[0]") # <=====
. . .
THEN("Extpect the following preemptions")
. . .

See also

• SCENARIO()
• GIVEN()
• THEN()
• AND()

Definition at line 225 of file qutest_dsl.py.

THEN()

qutest_dsl.THEN	(		self,
			msg = "",
			dest = 0x3 )

start the "then" section of a BDD-style scenario (alternative #1)

Description
This function that defines the "then" section of a BDD-scenario. The commands in this section typically include the expect() command. The THEN() section should follow the WHEN() section.

Parameters

[in]	msg	optional "when" message
[in]	dest	optional destination of the message (both screen and QSPY)

Usage

SCENARIO("extened->basic->extended")
GIVEN("basic thread priorities: 4,0,0")
. . .
AND("extended thread priorities: 1,5,0")
. . .
 
WHEN("post TEST0_SIG->thrX[0]")
. . .
THEN("Extpect the following preemptions") # <=====
. . .

See also

• SCENARIO()
• GIVEN()
• WHEN()
• AND()

Definition at line 258 of file qutest_dsl.py.

AND()

qutest_dsl.AND	(		self,
			msg = "",
			dest = 0x3 )

adds the "and" section of a BDD-style scenario (alternative #1)

Description
This function that defines the "and" section of a BDD-scenario. This section can augment the "given" or the "then" sections to better delimit the additional preconditions or additional effects.

Parameters

[in]	msg	optional "when" message
[in]	dest	optional destination of the message (both screen and QSPY)

Usage

SCENARIO("extened->basic->extended")
GIVEN("basic thread priorities: 4,0,0")
. . .
AND("extended thread priorities: 1,5,0") # <=====
. . .
 
WHEN("post TEST0_SIG->thrX[0]")
. . .
THEN("Extpect the following preemptions")
. . .

See also

• SCENARIO()
• GIVEN()
• WHEN()
• THEN()

Definition at line 290 of file qutest_dsl.py.

scenario()

qutest_dsl.scenario	(		title,
			opt = 0 )

start a new BDD-style scenario (alternative #2)

Description
This is a Python decorator to a function that starts a new BDD-style scenario.

Parameters

[in]	title	title of the scenario
[in]	opt	options {0=default, NORESET}

The @scenario() decorator outputs the provided title (text) to the QUTest output (text/log) and the QSPY output (text/log), adding the prefix "Scenario:" in front.

The decorated function must take the:

Parameters

[in,out]

context

execution context (clean context at the start of a scenario)

Note

The decorated function can have arbitrary name, but the example tests use the name do().

Returns

The decorated fucntion returs context (to let the QUTest system store any modifications to the context)

Usage

@scenario("my first test") # <=====
def do(context):
    context.x = ...
    ...
    return context

See also

• @given()
• @when()
• @then()
• test()
• skip()

Definition at line 334 of file qutest_dsl.py.

given()

qutest_dsl.given	(		given_msg,
			and_msg )

start the "given" section of a BDD-style scenario (alternative #2)

Description
This is a Python decorator to a function that defines the "given" section. The @given section typically sets up the context for the "given-when-then" sequence. Therefore, a @given section should follow @scenario() or it might follow the @then() section to define another "given-when-then" sequence.

Parameters

[in]	given_msg	optional "given" message
[in]	and_msg	optional "and" messages

The @given() command outputs the provided given_msg (text) to the QUTest output (text/log) and the QSPY output (text/log), adding the prefix "Given:" in front. Additionally, every subsequent and_msg is also output with the prefix "And:".

The decorated function must take the:

Parameters

[in,out]

context

execution context

Note

The decorated function can have arbitrary name, but the example tests use the name do().

Returns

The decorated fucntion returs context (to let the QUTest system store any modifications to the context)

Usage

@scenario("my first test", NORESET)
def do(context):
    glb_filter(GRP_SC, GRP_UA)
    current_obj(OBJ_AP, "pspecB")
    ...
    context.x = ...
    ...
    return context
 
@given("provided that y=123") # <=====
def do(context):
    context.y = 123
    ...
    return context

See also

• @scenario()
• @when()
• @then()
• test()
• skip()

Definition at line 393 of file qutest_dsl.py.

when()

qutest_dsl.when	(		given_msg,
			and_msg )

start the "when" section of a BDD-style scenario (alternative #2)

Description
This is a Python decorator to a function that defines the "when" section. The @when section typically executes a command() or post() command. The @when section should follow the @given() section.

Parameters

[in]	when_msg	optional "when" message
[in]	and_msg	optional "and" messages

The @when() command outputs the provided when_msg (text) to the QUTest output (text/log) and the QSPY output (text/log), adding the prefix "When:" in front. Additionally, every subsequent and_msg is also output with the prefix "And:".

The decorated function must take the:

Parameters

[in,out]

context

execution context

Note

The decorated function can have arbitrary name, but the example tests use the name do().

Usage

@scenario("my first test")
def do(context):
    ...
    return context
 
@given("provided that y=123")
def do(context):
    ...
    return context
 
@when("provided that y=123") # <=====
def do(context):
    command(1, context.x, context.y)

See also

• @scenario()
• @given()
• @then()
• test()
• skip()

Definition at line 444 of file qutest_dsl.py.

then()

qutest_dsl.then	(		given_msg,
			and_msg )

start the "then" section of a BDD-style scenario (alternative #2)

Description
This is a Python decorator to a function that defines the "then" section. The @then section typically calls the expect() commands to verify the expectaion of the "given-when-then" sequence. The @then section should follow the @when() section.

Parameters

[in]	then_msg	optional "then" message
[in]	and_msg	optional "and" messages

The @then command outputs the provided then_msg (text) to the QUTest output (text/log) and the QSPY output (text/log), adding the prefix "Then:" in front. Additionally, every subsequent and_msg is also output with the prefix "And:".

The decorated function must take the:

Parameters

[in,out]

context

execution context

Note

The decorated function can have arbitrary name, but the example tests use the name do().

Usage

@scenario("my first test")
def do(context):
    ...
    return context
 
@given("provided that y=123")
def do(context):
    ...
    return context
 
@when("provided that y=123") # <=====
def do(context):
    command(1, context.x, context.y)
 
@then("the following sequence shall happen...") # <=====
def do(context):
    expect(f"... {context.y} ...")
    expect(f"... {context.x} ...")

See also

• @scenario()
• @given()
• @when()
• test()
• skip()

Definition at line 500 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]

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 529 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_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 543 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]

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 588 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]

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 621 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_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 645 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_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_EP # Event Pool
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

• query_curr()
• init()
• dispatch()
• post()

Definition at line 678 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_kind

Kind of object to query

This parameter can take one of the following values:

OBJ_SM # State Machine
OBJ_AO # Active Object
OBJ_MP # Memory Pool
OBJ_EQ # Event Queue
OBJ_TE # Time Event
OBJ_EP # Event Pool

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>,Que<Use=<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>"
query_curr(OBJ_MP)
"@timestamp Query-EP Pool-<id> <Use=<n>,Min=<m>>"

See also

current_obj()

Definition at line 719 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_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 739 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 757 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 775 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 788 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]

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 811 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 complex 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))
~ ~ ~
expect("@timestamp Trg-Done QS_RX_EVENT")

Definition at line 832 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]	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))
~ ~ ~
expect("@timestamp Trg-Done QS_RX_EVENT")

Definition at line 851 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 complex 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))
~ ~ ~
expect("@timestamp Trg-Done QS_RX_EVENT")

Definition at line 870 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]	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))
~ ~ ~
expect("@timestamp Trg-Done QS_RX_EVENT")

Definition at line 889 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]	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 916 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]	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)
~ ~ ~
expect("@timestamp Trg-Peek ...")

Definition at line 937 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]	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 957 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]	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 977 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]	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 999 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 1007 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 <strong>Usage</strong><br> @code{py} dispatch("MY_SIG", pack("<B", 2)) poke(2, 2, pack("<HH", 0xB2C2, 0xD2E2))

Definition at line 1031 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 1048 of file qutest_dsl.py.

on_reset()

qutest_dsl.on_reset

(

)

callback function invoked after each Target reset

Description
If defined, this callback should handle the expectations and end with expect_run(). If not defiend, the default implementation only expects QF_RUN.

Note

If any output is generated before QF_RUN, the test script should define this on_reaset() callback to expect that output.

Definition at line 1059 of file qutest_dsl.py.

on_setup()

qutest_dsl.on_setup

(

)

callback function invoked at the beginning of each test

Definition at line 1064 of file qutest_dsl.py.

on_teardown()

qutest_dsl.on_teardown

(

)

callback function invoked at the end of each test

Definition at line 1069 of file qutest_dsl.py.

Variable Documentation

VERSION

int qutest_dsl.VERSION = 740

current version of the Python QUTest interface

Definition at line 30 of file qutest_dsl.py.