QTools  7.4.0
Collection of Host-Based Tools
Loading...
Searching...
No Matches
qutest_dsl.py
Go to the documentation of this file.
1#=============================================================================
2# QUTest Python scripting support
3# Copyright (C) 2005 Quantum Leaps, LLC. All rights reserved.
4#
5# SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-QL-commercial
6#
7# This software is dual-licensed under the terms of the open source GNU
8# General Public License version 3 (or any later version), or alternatively,
9# under the terms of one of the closed source Quantum Leaps commercial
10# licenses.
11#
12# The terms of the open source GNU General Public License version 3
13# can be found at: <www.gnu.org/licenses/gpl-3.0>
14#
15# The terms of the closed source Quantum Leaps commercial licenses
16# can be found at: <www.state-machine.com/licensing>
17#
18# Redistributions in source code must retain this top-level comment block.
19# Plagiarizing this software to sidestep the license obligations is illegal.
20#
21# Contact information:
22# <www.state-machine.com>
23# <info@state-machine.com>
24#=============================================================================
25##
26# @date Last updated on: 2024-06-13
27# @version Last updated for version: 7.4.0
28#
29# @file
30# @brief QUTest Python scripting support (documentation)
31
32## @brief current version of the Python QUTest interface
33VERSION = 740
34
35## @brief include python code in a test script
36# @description
37# This @ref qutest_dsl-preamble "preamble command" includes python code
38# in a specified file into the test script. The included file can contain
39# any code that you would put into test scripts (see Example below).
40#
41# @param[in] fname name of the file to include. May contain a path
42# **relative** to the test script.
43#
44# @usage
45# @code{py}
46# include("test_include.pyi") # file in the same directory as the script
47# ~ ~ ~
48# include("../my_include/test_include.pyi") # relative directory
49# @endcode
50#
51# __Example__<br>
52# file to be included:<br>
53# @include inc_file.py
54#
55# test script calling `include()`:<br>
56# @include inc_test.py
57#
58def include(fname):
59
60## @brief get the test file name with path
61# @description
62# This command returns a string containing the file name of the currently
63# executed test script ("test group").
64#
65# @usage
66# @code{py}
67# file_name = test_file()
68# @endcode
70
71## @brief get the test directory (relative to the current directory)
72# @description
73# This @ref qutest_complex "complex command" returns a string containing
74# the directory name of the currently executed test script ("test group").
75#
76# @usage
77# @code{py}
78# dir_name = test_dir()
79# @endcode
81
82## @brief start a new test
83# @description
84# This @ref qutest_complex "complex command" starts a new test
85# and gives it a name.
86#
87# @param[in] title title of the test
88# @param[in] opt options {0=default, NORESET}
89#
90# @usage
91# @code{py}
92# test("my first test") # test with title and with full target reset
93# ~ ~ ~
94# test("my second test", NORESET) # test without target reset
95# ~ ~ ~
96# @endcode
97#
98# @sa skip() @ref scenario() "\@scenario()"
99#
100def test(title, opt=0):
101
102## @brief skip the tests following this command.
103#
104# @param[in] nTests number of tests to skip (default-all remaining tests)
105# e.g., skip(1) will skip one test following this command.
106# @note
107# The skipped tests are not executed, but they **are** checked for syntax
108# errors, such as commands and parameters coded in the skipped tests.
109#
110# @usage
111# @code{py}
112# test("my first test")
113# ~ ~ ~
114# skip(1) # skip one subsequent test
115# test("my second test")
116# ~ ~ ~
117# skip() # skip all subsequent tests
118# test("my second test")
119# ~ ~ ~
120# @endcode
121#
122# @sa
123# test()
124#
125def skip(nTests=9999):
126
127## @brief start a new BDD-style scenario
128# @description
129# This is a Python decorator to a function that starts a new BDD-style scenario.
130#
131# @param[in] title title of the scenario
132# @param[in] opt options {0=default, NORESET}
133#
134# The `@scenario()` command outputs the provided `title` (text) to the
135# QUTest output (text/log) and the QSPY output (text/log), adding the prefix
136# "Scenario:" in front.
137#
138# The _decorated function_ must take the:
139#
140# @param[in,out] context execution context
141# (clean context at the start of a scenario)
142#
143# @note
144# The decorated function can have arbitrary name, but the example tests
145# use the name `do()`.
146#
147# @returns
148# The decorated fucntion returs `context` (to let the QUTest system
149# store any modifications to the `context`)
150#
151# @usage
152# @code{py}
153# @scenario("my first test") # <==
154# def do(context):
155# context.x = ...
156# ...
157# return context
158# @endcode
159#
160# @sa
161# - @ref qutest_dsl::given() "\@given()"
162# - @ref qutest_dsl::when() "\@when()"
163# - @ref qutest_dsl::then() "\@then()"
164# - test()
165# - skip()
166#
167def @scenario(title, opt=0):
168
169## @brief start the "given" section of a BDD-style scenario
170# @description
171# This is a Python decorator to a function that defines the "given" section.
172# The `@given` section typically sets up the context for the "given-when-then"
173# sequence. Therefore, a `@given` section should follow
174# @ref qutest_dsl::scenario() "\@scenario()" or it might follow the
175# @ref qutest_dsl::then() "\@then()" section to define another "given-when-then"
176# sequence.
177#
178# @param[in] given_msg optional "given" message
179# @param[in] and_msg optional "and" messages
180#
181# The `@given()` command outputs the provided `given_msg` (text) to the
182# QUTest output (text/log) and the QSPY output (text/log), adding the prefix
183# "Given:" in front. Additionally, every subsequent `and_msg` is also output
184# with the prefix "And:".
185#
186# The _decorated function_ must take the:
187#
188# @param[in,out] context execution context
189#
190# @note
191# The decorated function can have arbitrary name, but the example tests
192# use the name `do()`.
193#
194# @returns
195# The decorated fucntion returs `context` (to let the QUTest system
196# store any modifications to the `context`)
197#
198# @usage
199# @code{py}
200# @scenario("my first test", NORESET)
201# def do(context):
202# glb_filter(GRP_SC, GRP_UA)
203# current_obj(OBJ_AP, "pspecB")
204# ...
205# context.x = ...
206# ...
207# return context
208#
209# @given("provided that y=123") # <==
210# def do(context):
211# context.y = 123
212# ...
213# return context
214#
215# @endcode
216#
217# @sa
218# - @ref qutest_dsl::scenario() "\@scenario()"
219# - @ref qutest_dsl::when() "\@when()"
220# - @ref qutest_dsl::then() "\@then()"
221# - test()
222# - skip()
223#
224def @given(given_msg, and_msg, ...):
225
226
227## @brief start the "when" section of a BDD-style scenario
228# @description
229# This is a Python decorator to a function that defines the "when" section.
230# The `@when` section typically executes a @ref qutest_dsl::command() "command()"
231# or @ref qutest_dsl::post() "post()" command. The `@when` section should follow
232# the @ref qutest_dsl::given() "\@given()" section.
233#
234# @param[in] when_msg optional "when" message
235# @param[in] and_msg optional "and" messages
236#
237# The `@when()` command outputs the provided `when_msg` (text) to the
238# QUTest output (text/log) and the QSPY output (text/log), adding the prefix
239# "When:" in front. Additionally, every subsequent `and_msg` is also output
240# with the prefix "And:".
241#
242# The _decorated function_ must take the:
243#
244# @param[in,out] context execution context
245#
246# @note
247# The decorated function can have arbitrary name, but the example tests
248# use the name `do()`.
249#
250# @usage
251# @code{py}
252# @scenario("my first test")
253# def do(context):
254# ...
255# return context
256#
257# @given("provided that y=123")
258# def do(context):
259# ...
260# return context
261#
262# @when("provided that y=123") # <==
263# def do(context):
264# command(1, context.x, context.y)
265# @endcode
266#
267# @sa
268# - @ref qutest_dsl::scenario() "\@scenario()"
269# - @ref qutest_dsl::given() "\@given()"
270# - @ref qutest_dsl::then() "\@then()"
271# - test()
272# - skip()
273#
274def @when(given_msg, and_msg, ...):
275
276## @brief start the "then" section of a BDD-style scenario
277# @description
278# This is a Python decorator to a function that defines the "then" section.
279# The `@then` section typically calls the @ref qutest_dsl::expect() "expect()"
280# commands to verify the expectaion of the "given-when-then" sequence.
281# The `@then` section should follow the @ref qutest_dsl::when() "\@when()"
282# section.
283#
284# @param[in] then_msg optional "then" message
285# @param[in] and_msg optional "and" messages
286#
287# The `@then` command outputs the provided `then_msg` (text) to the
288# QUTest output (text/log) and the QSPY output (text/log), adding the prefix
289# "Then:" in front. Additionally, every subsequent `and_msg` is also output
290# with the prefix "And:".
291#
292# The _decorated function_ must take the:
293#
294# @param[in,out] context execution context
295#
296# @note
297# The decorated function can have arbitrary name, but the example tests
298# use the name `do()`.
299#
300# @usage
301# @code{py}
302# @scenario("my first test")
303# def do(context):
304# ...
305# return context
306#
307# @given("provided that y=123")
308# def do(context):
309# ...
310# return context
311#
312# @when("provided that y=123") # <==
313# def do(context):
314# command(1, context.x, context.y)
315#
316# @then("the following sequence shall happen...") # <==
317# def do(context):
318# expect(f"... {context.y} ...")
319# expect(f"... {context.x} ...")
320# @endcode
321#
322# @sa
323# - @ref qutest_dsl::scenario() "\@scenario()"
324# - @ref qutest_dsl::given() "\@given()"
325# - @ref qutest_dsl::when() "\@when()"
326# - test()
327# - skip()
328#
329def @then(given_msg, and_msg, ...):
330
331
332## @brief defines an expectation for the current test
333#
334# @description
335# This command defines a new expecation for the textual output produced
336# by QSPY.
337#
338# @param[in] match the expected match for the QSPY output
339# The @p match string can contain special characters, such as:
340# `*`, `?` and `[chars]`, which are matched according to the
341# Python command
342# [fnmatch.fnmatchcase()](https://docs.python.org/2/library/fnmatch.html)
343# @note
344# The @p match string can be the
345# [printf-style %-subsitution string](https://docs.python.org/2/library/stdtypes.html#string-formatting-operations)
346# (compatible with Python 2 and Python 3), or the new
347# ["f-string"](https://realpython.com/python-f-strings/)
348# (compatible only with Python 3).
349#
350# @note
351# The special string "@timestamp" (or "%timestamp") at the beginning
352# of the @p match parameter will be automatically replaced with the current
353# numerical value of the test sequence-counter.
354#
355# @usage
356# @include expect.py
357#
358def expect(match):
359
360## @brief ensures that the provided Boolean expression is true
361#
362# @description
363# This command performs checking of a condition, which is believed to be true
364# in order for a test to pass. If the provided Boolean expression evaluates
365# to false, the test is failed in the usual way.
366#
367# @param[in] bool_expr the Boolean expression to check
368#
369# @usage
370# @include ensure.py
371#
372def ensure(bool_expr):
373
374## @brief Send the QS Global Filter to the Target
375#
376# @description
377# This @ref qutest_simple "simple command" sends the complete
378# @ref qs_global "QS Global Filter" to the Target.
379# Any existing Global Filter setting inside the Target will be overwritten.
380#
381# @param[in] args list of Record-Type groups or individual Record-Types
382# to set or clear. A given filter-group or an individual filter is set when
383# it is positive, and cleared with it is preceded with the minus (`-`) sign.
384# <br>
385# The filter list can contain the following:
386# @code{py}
387# GRP_ALL # all Record-Types
388# GRP_SM # State Machine Record-Types
389# GRP_AO # Active Object Record-Types
390# GRP_MP # Memory Pool Record-Types
391# GRP_EQ # Event Queue Record-Types
392# GRP_TE # Time Events Record-Types
393# GRP_QF # Framework Record-Types (e.g., post/publish/..)
394# GRP_SC # Scheduler Record-Types (e.g., scheduler lock/unlock)
395# GRP_SEM # Semaphore Record-Types (e.g., Semaphore take/signal)
396# GRP_MTX # Mutex Record-Types (e.g., Mutex lock/unlock)
397# GRP_U0 # User group 0 (Record-Types 100-104)
398# GRP_U1 # User group 1 (Record-Types 105-109)
399# GRP_U2 # User group 2 (Record-Types 110-114)
400# GRP_U3 # User group 3 (Record-Types 115-119)
401# GRP_U4 # User group 0 (Record-Types 120-124)
402# GRP_UA # All user records (Record-Types 100-124)
403# <num> # Specific QS trace Record-Type in the range 0..127
404# @endcode
405#
406# @returns
407# The 128-bit filter bitmask sent to the target. For each enabled filter
408# with the QS record-ID `recID` the bitmask has a '1' in the position
409# (`1 << recID`).
410#
411# @usage
412# @include glb_filter.py
413#
414# @sa
415# loc_filter()
416#
417def glb_filter(*args):
418
419## @brief Send the Local Filter to the Target
420#
421# @description
422# This @ref qutest_simple "simple command" sends the complete
423# @ref qs_local "QS Local Filter" to the Target.
424# Any existing Local Filter setting inside the Target will be overwritten.
425#
426# @param[in] args list of QS-ID groups or individual QS-IDs to set or clear.
427# A given filter-group or an individual filter is set when it is positive, and
428# cleared with it is preceded with the minus (`-`) sign.<br>
429#
430# This parameter can take one of the following values:
431# @code{py}
432# IDS_ALL # all QS-IDs
433# IDS_AO # Active Object QS-IDs (1..64)
434# IDS_EP # Event Pool QS-IDs (65-80)
435# IDS_EQ # Event Queue QS-IDs (81-96)
436# IDS_AP # Application-Specific QS-IDs (97-127)
437# @endcode
438#
439# @returns
440# The 128-bit filter bitmask sent to the target. For each enabled filter
441# with the QS-ID `qsID` the bitmask has a '1' in the position
442# (`1 << qsID`).
443#
444# @usage
445# @include loc_filter.py
446#
447# @sa
448# glb_filter()
449#
450def loc_filter(*args):
451
452## @brief Updates the Local Filter for a given AO in the Target
453#
454# @description
455# This @ref qutest_simple "simple command" sets or clears the
456# @ref qs_local "QS Local Filter" corresponding to the given AO in the Target.
457# Unlike loc_filter(), this facility changes **only** the QS-ID
458# (AO's priority) of the given AO in the Target.
459# All other Local Filters will be left unchanged.
460#
461# @param[in] obj_id active object to set/clear the local filter
462# for in the Target<br>
463#
464# This parameter can be either a string (name of the AO) or the AO's priority.
465# Also, it can be either positive (to set) or negative (to clear) the QS
466# local filter.
467#
468# @usage
469# @include ao_filter.py
470#
471# @sa
472# loc_filter()
473#
474def ao_filter(obj_id):
475
476## @brief Set the Current-Object in the Target
477#
478# @description
479# This @ref qutest_simple "simple command" sets the "current object"
480# in the Target.
481#
482# @param[in] obj_kind Kind of object to set<br>
483#
484# This parameter can take one of the following values:
485# @code{py}
486# OBJ_SM # State Machine object
487# OBJ_AO # Active Object object
488# OBJ_MP # Memory Pool object
489# OBJ_EQ # Event Queue object
490# OBJ_TE # Time Event object
491# OBJ_AP # Application-Specific object
492# OBJ_SM_AO # Both, State Machine and Active Object
493# @endcode
494#
495# @param[in] obj_id Name or addres of the object
496#
497# @usage
498# @include current_obj.py
499#
500# @sa
501# - query_curr()
502# - init()
503# - dispatch()
504#
505def current_obj(obj_kind, obj_id):
506
507## @brief query the @ref current_obj() "current object" in the Target
508#
509# @description
510# This @ref qutest_complex "complex command" queries the current object
511# in the Target.
512#
513# @param[in] obj_kind Kind of object to query
514#
515# This parameter can take one of the following values:
516# @code{py}
517# OBJ_SM # State Machine object
518# OBJ_AO # Active Object object
519# OBJ_MP # Memory Pool object
520# OBJ_EQ # Event Queue object
521# OBJ_TE # Time Event object
522# @endcode
523#
524# @usage
525# The queries for various objects generate the following QS trace records
526# from the Target
527# @code{py}
528# query_curr(OBJ_SM)
529# "@timestamp Query-SM Obj=<obj-name>,State=<state-name>"
530# query_curr(OBJ_AO)
531# "@timestamp Query-AO Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
532# query_curr(OBJ_EQ)
533# "@timestamp Query-EQ Obj=<obj-name>,Queue<Free=<n>,Min=<m>>"
534# query_curr(OBJ_MP)
535# "@timestamp Query-MP Obj=<obj-name>,Free=<n>,Min=<m>"
536# query_curr(OBJ_TE)
537# "@timestamp Query-TE Obj=<obj-name>,Rate=<r>,Sig=<s>,Tim=<n>,Int=<m>,Flags=<f>"
538# @endcode
539#
540# @sa
541# current_obj()
542#
543def query_curr(obj_kind):
544
545## @brief trigger system clock tick in the Target
546#
547# @description
548# This @ref qutest_complex "complex command" triggers the following actions
549# in the Target:<br>
550# 1. If the @ref current_obj() "current TE object" is defined and
551# the TE is armed, the TE is disarmed (if one-shot) and then
552# posted to the recipient AO.
553# 2. The linked-list of all armed Time Events is updated.
554#
555# @param[in] tick_rate the tick rate (0..QF_MAX_TICK_RATE)
556#
557# @usage
558# @include tick.py
559#
560# @sa
561# current_obj()
562#
563def tick(tick_rate=0):
564
565## @brief defines expectation for a Test Pause
566#
567# @description
568# This is a special expectation that must match the macro
569# QS_TEST_PAUSE() inside the test fixture.
570#
571# @note
572# If QS_TEST_PAUSE() is called before QF_run(), the `expect_pause()`
573# expectation must be placed in the on_reset() callback.
574#
575# @usage
576# @include expect_pause.py
577#
578# @sa
579# continue_test()
580#
582
583## @brief defines expectation for calling QF_run()/QF::run()
584#
585# @description
586# This is a special expectation for the target calling the QF_run()/QF::run()
587# function.
588#
589# @note
590# This expectation must be placed at the right place in the
591# on_reset() callback.
592#
593# @usage
594# @include expect_run.py
595#
596# @sa
597# on_reset()
598#
600
601## @brief sends the CONTINUE packet to the Target to continue a test
602#
603# @description
604# This command continues the test after QS_TEST_PAUSE().
605#
606# @usage
607# @include continue_test.py
608#
609# @sa
610# expect_pause()
611#
613
614## @brief executes a given command in the Target
615# @description
616# This @ref qutest_complex "complex command" causes execution of the
617# @ref QS_rx::QS_onCommand() "QS_onCommand()" callback in the test fixture.
618#
619# @param[in] cmdId the first `cmdId` argument for the
620# @ref QS_rx::QS_onCommand() "QS_onCommand()" callback
621# function in the test fixture.
622# @note
623# The `cmdId` parameter could be either the raw number or a name
624# that is delivered by QS_ENUM_DICTIONARY(enum, group), where the
625# second `group` argument is ::QS_CMD (numerical value 7).
626#
627# @param[in] param1 the "param1" argument to `QS_onCommand()` (optional)
628# @param[in] param2 the "param2" argument to `QS_onCommand()` (optional)
629# @param[in] param3 the "param3" argument to `QS_onCommand()` (optional)
630#
631# @usage
632# @include command.py
633#
634def command(cmdId, param1=0, param2=0, param3=0):
635
636## @brief take the top-most initial transition in the
637# current SM object in the Target
638#
639# @description
640# This @ref qutest_complex "complex command" takes the top-most initial transition in the
641# @ref current_obj() "current SM object" in the Target.
642#
643# @param[in] signal the event signal of the "initialization event"
644# @param[in] params the parameters of the "initialization event"
645#
646# @usage
647# @code{py}
648# init()
649# init("MY_SIG")
650# init("MY_SIG", pack("<B", 2))
651# ~ ~ ~
652# expect("@timestamp Trg-Done QS_RX_EVENT")
653# @endcode
654#
655def init(signal=0, params=None):
656
657## @brief dispatch a given event in the current SM object in the Target
658#
659# @description
660# This @ref qutest_complex "complex command" dispatches a given event in the
661# @ref current_obj() "current SM object" in the Target.
662#
663# @param[in] signal the event signal of the event to be dispatched
664# @param[in] params the parameters of the event to be dispatched
665#
666# @usage
667# @code{py}
668# dispatch("MY_SIG")
669# dispatch("MY_SIG", pack("<B", 2))
670# ~ ~ ~
671# expect("@timestamp Trg-Done QS_RX_EVENT")
672# @endcode
673#
674def dispatch(signal, params=None):
675
676## @brief post a given event to the current AO object in the Target
677#
678# @description
679# This @ref qutest_complex "complex command" posts a given event to the
680# @ref current_obj() "current AO object" in the Target.
681#
682# @param[in] signal the event signal of the event to be posted
683# @param[in] params the parameters of the event to be posted
684#
685# @usage
686# @code{py}
687# post("MY_SIG")
688# post("MY_SIG", pack("<B", 2))
689# ~ ~ ~
690# expect("@timestamp Trg-Done QS_RX_EVENT")
691# @endcode
692#
693def post(signal, params=None):
694
695## @brief publish a given event to subscribers in the Target
696#
697# @description
698# This @ref qutest_complex "complex command" publishes a given event
699# in the Target.
700#
701# @param[in] signal the event signal of the event to be posted
702# @param[in] params the parameters of the event to be posted
703#
704# @usage
705# @code{py}
706# publish("MY_SIG")
707# publish("MY_SIG", pack("<B", 2))
708# ~ ~ ~
709# expect("@timestamp Trg-Done QS_RX_EVENT")
710# @endcode
711#
712def publish(signal, params=None):
713
714## @brief sends a Test-Probe to the Target
715# @description
716# This @ref qutest_simple "simple command" sends the Test Probe data
717# to the Target. The Target collects these Test Probes preserving the
718# order in which they were sent. Subsequently, whenever a given API is
719# called inside the Target, it can obtain the Test-Probe by means of the
720# QS_TEST_PROBE_DEF() macro.
721# The QS_TEST_PROBE_DEF() macro returns the Test-Probes in the same
722# order as they were received to the Target. If there are no more Test-
723# Probes for a given API, the Test-Probe is initialized to zero.
724#
725# @param[in] func the name or raw address of a function
726# @param[in] data the data (uint32_t) for the Test-Probe
727#
728# @note
729# All Test-Probes are cleared when the Target resets and also upon the
730# start of a new test, even if this test does not reset the Target
731# (NORESET tests).
732#
733# @usage
734# @code{py}
735# probe("myFunction", 123)
736# @endcode
737#
738def probe(func, data):
739
740## @brief peeks data in the Target
741#
742# @description
743# This @ref qutest_complex "complex command" peeks data at the given offset
744# from the start address of the current_obj() inside the Target.
745#
746# @param[in] offset offset [in bytes] from the start of the current_obj()
747# @param[in] size size of the data items (1, 2, or 4)
748# @param[in] num number of data items to peek
749#
750# @usage
751# @code{py}
752# peek(0, 1, 10)
753# peek(8, 2, 4)
754# peek(4, 4, 2)
755# ~ ~ ~
756# expect("@timestamp Trg-Peek ...")
757# @endcode
758#
759def peek(offset, size, num):
760
761## @brief pokes data into the Target.
762# @description
763# This @ref qutest_simple "simple command" pokes provided data at the
764# given offset from the start address of the
765# @ref current_obj() "current AP object" inside the Target.
766#
767# @param[in] offset offset [in bytes] from the start of the current_obj()
768# @param[in] size size of the data items (1, 2, or 4)
769# @param[in] data binary data to send
770#
771# @usage
772# @code{py}
773# poke(4,4,pack("<II",0xB4C4D4E4,0xB5C5D5E5))
774# poke(0, 1, bytearray("dec=%d\0", "ascii"))
775# poke(0, 1, bytes("Hello World!\0","ascii"))
776# @endcode
777#
778def poke(offset, size, data):
779
780## @brief fills data into the Target.
781# @description
782# This @ref qutest_simple "simple command" fills provided data at the
783# given offset from the start address of the current_obj() inside the Target.
784#
785# @param[in] offset offset [in bytes] from the start of the current_obj()
786# @param[in] size size of the data item (1, 2, or 4)
787# @param[in] num number of data items to fill
788# @param[in] item data item to fill with
789#
790# @usage
791# @code{py}
792# fill(0, 1, 100, 0x1A)
793# fill(0, 2, 50, 0x2A2B)
794# fill(0, 4, 25, 0x4A4B4C4D)
795# @endcode
796#
797def fill(offset, size, num, item=0):
798
799## @brief display a note in the QUTest output and in QSPY output.
800# @description
801# This command allows the test script to output a note (text) both
802# to the QUTest output (text/log) and the QSPY output (text/log).
803# This command can be also used for commenting the test scripts.
804#
805# @param[in] msg text message
806# @param[in] dest destination (SCREEN, TRACE), default both
807# @usage
808# @code{py}
809# note("This is a short note")
810#
811# note('''
812# This test group checks the MPU (Memory Protection Unit)
813# by reading/writing from/to various memory addresses
814# in the target
815# ''', SCREEN)
816# @endcode
817#
818def note(msg, dest=(SCREEN | TRACE)):
819
820## @brief display a tag in the QUTest output and in QSPY output.
821# @description
822# This is an alias for the note() command for the BDD-style
823# testing.
824#
825def tag(msg, dest=(SCREEN | TRACE)):
826
827## @brief packs data into binary string to be sent to QSPY.
828# @description
829# This command corresponds to Python
830# [struct.pack()](https://docs.python.org/3/library/struct.html).
831# It returns a bytes object containing the values v1, v2,... packed
832# according to the format string @p format. The arguments must match
833# the values required by the
834# [format](https://docs.python.org/3/library/struct.html#format-strings") exactly.
835# The pack() command is typically used inside other QUTest commands
836# to pack the binary event parameters or binary data for poke() and fill().
837#
838# @param[in] format string
839# @param[in] v1 one or more data elements requried by format
840# @param[in] v2 one or more data elements requried by format
841#
842# @usage
843# @code{py}
844# dispatch("MY_SIG", pack("<B", 2))
845# poke(2, 2, pack("<HH", 0xB2C2, 0xD2E2))
846# @endcode
847#
848def pack(format, v1, v2, ...):
849
850## @brief returns last record received from the target as string.
851#
852# @usage
853# @code{py}
854# command("COMMAND_B", 123, 23456, 3456789) # generate record (if needed)
855# expect("@timestamp COMMAND_B *") # expect the record from the target
856# last = last_rec().split() # <-- obtain the last record and split it
857# p1 = int(last[2]) # extract the expected parameter p1 (int)
858# s1 = last[3] # extract the expected string s1
859# p2 = int(last[4]) # extract the expected parameter p2 (int)
860# s2 = last[5] # extract the expected string s2
861# p3 = int(last[6]) # extract the expected parameter p3 (int)
862# p4 = float(last[7]) # extract the expected parameter p4 (float)
863# @endcode
864#
866
867## @brief
868# callback function invoked after each Target reset
870
871## @brief
872# callback function invoked at the beginning of each test
874
875## @brief
876# callback function invoked at the end of each test
post(signal, params=None)
post a given event to the current AO object in the Target
then(given_msg, and_msg)
start the "then" section of a BDD-style scenario
on_reset()
callback function invoked after each Target reset
tick(tick_rate=0)
trigger system clock tick in the Target
peek(offset, size, num)
peeks data in the Target
when(given_msg, and_msg)
start the "when" section of a BDD-style scenario
skip(nTests=9999)
skip the tests following this command.
on_teardown()
callback function invoked at the end of each test
init(signal=0, params=None)
take the top-most initial transition in the current SM object in the Target
glb_filter(*args)
Send the QS Global Filter to the Target.
continue_test()
sends the CONTINUE packet to the Target to continue a test
test_dir()
get the test directory (relative to the current directory)
Definition qutest_dsl.py:80
expect_run()
defines expectation for calling QF_run()/QFrun()
fill(offset, size, num, item=0)
fills data into the Target.
probe(func, data)
sends a Test-Probe to the Target
expect(match)
defines an expectation for the current test
command(cmdId, param1=0, param2=0, param3=0)
executes a given command in the Target
note(msg, dest=(SCREEN|TRACE))
display a note in the QUTest output and in QSPY output.
query_curr(obj_kind)
query the current object in the Target
loc_filter(*args)
Send the Local Filter to the Target.
tag(msg, dest=(SCREEN|TRACE))
display a tag in the QUTest output and in QSPY output.
given(given_msg, and_msg)
start the "given" section of a BDD-style scenario
current_obj(obj_kind, obj_id)
Set the Current-Object in the Target.
expect_pause()
defines expectation for a Test Pause
on_setup()
callback function invoked at the beginning of each test
include(fname)
include python code in a test script
Definition qutest_dsl.py:58
test(title, opt=0)
start a new test
poke(offset, size, data)
pokes data into the Target.
test_file()
get the test file name with path
Definition qutest_dsl.py:69
pack(format, v1, v2)
packs data into binary string to be sent to QSPY.
ensure(bool_expr)
ensures that the provided Boolean expression is true
dispatch(signal, params=None)
dispatch a given event in the current SM object in the Target
last_rec()
returns last record received from the target as string.
publish(signal, params=None)
publish a given event to subscribers in the Target
ao_filter(obj_id)
Updates the Local Filter for a given AO in the Target.