Test::Async::Hub - the core of Test::Async framework
if test-suite.random {
say "The current suite is in random mode"
}Consumes Test::Async::Aggregator, Test::Async::JobMgr
See Test::Async::Manual for general purpose of this class.
All events whose class derives from Event::Command are handled in a special manner. Class name of such event is used to form a method name. Corresponding method is then invoked with a Capture passed in event's attribute $.args. For example, to mark all remaining tests as skipped, event Event::Cmd::SkipRemaining is used. Based on the class, method cmd-skipremaining is invoked with a single positional string argument in $.args containing the skip message if the event has been created without an error.
Method send-command is recommended to emit command messages.
See method set-todo or sync-events for an example of using this interface.
If defined then it's the suite which invoked the current one.
Message associated with this suite. Only makes sense for children.
The code block associated with the suite. Undefined for the top one.
A Promise instance which is fulfilled when done-testing is executed.
The number of tests planned for this suite. Undefined if no plans were made.
If suite is planned for skipping then this is the message as for skip-remaining tool:
subtest "Conditional test" => {
plan |($condition ?? :skip-all('makes no sens because ...') !! Empty);
pass "dummy test";
}Otherwise undefined.
NOTE! Any examples of code in this documentation are based on the default Test::Async::Base bundle.
If suite is planned for TODO then this is the message as for any of todo test tools.
A number of remaining TODO tests:
todo "To be done yet...", 3;
pass "test 1";
# -> test-suite.TODO-count == 2 at this point
flunk "test 2";
pass "test 3";Could be set to Inf meaning all remaining tests are to be TODO-marked.
How deep are we from the top suite? I.e. a child of a child of the top suite will have nesting 2.
A string, recommended prefix to be used for indenting messages produced by the suite.
An instance of Test::Async::Hub::ToolCallerCtx. Keeps information about the location where the suite was created.
A flag. If True then this suite will have its call location set to the where it's enclosing test tool or suite are called. subtest implementation by Test::Async::Base uses this for :hidden mode of operation.
This attribute is propagated to child suites instantiated using create-suite method. In other words, nested suites of a transparent one will all be transparent by default.
True if the suite itself or any of its parents is invoked asynchronously.
Indicates if the whole suite has been marked as TODO. This makes difference between:
todo "Later...";
subtest "new feature" => { ... }and
subtest "new feature" => {
todo-remaining "Later...";
...
}Also True if todo parameter of plan is set to a message, which is virtually the same as prefixing the subtest with todo.
True if suite is invoking children suites asynchronously.
True if suite is invoking children suites in a random order.
The counter of test tool invocations.
The counter of failed test tools.
An array of message lines produced by the suite and its child suites if it is an asynchronous child. I.e. if is-async is True. The messages are submitted for reporting when the suite run ends and its result is reported.
Maximus number of concurrently running jobs allowed. Note that a job is anything invoked using start-job method of Test::Async::JobMgr.
The current stage of suite lifecycle. See TestStage enum in Test::Async::Utils.
Creates a new instance of constructed Test::Async::Suite class. See Test::Async::Manual.
Returns a singleton – the top suite object.
Returns True if the top suite singleton has been instantiated already.
Transition suite state to stage $stage. Throws Test::Async::X::StageTransition (Test::Async::X) if the transition is not possible. If transitions from TSInitializing to TSInProgress then the method also starts the event loop thread.
Returns the pre-transition stage.
The ultimate handler of event objects. A bundle wishing to react to events must define a multi-candidate of this method:
test-bundle MyBundle {
multi method event(Event::Telemetry:D $ev) {
...
}
}Setup suite parameters based on a plan profile hash. If called when suite stage is not TSInitializing then throws Test::Async::X::PlanTooLate.
The keys supported by profile are:
-
tests - planned number of tests.
-
skip-all - a string with a skip message. If set all tests are skipped as if
skip-remainingis used. -
todo - a string with a TODO message. If set all tests and suite itself are marked as TODO.
-
parallel – invoke children suites asynchronously.
-
random – invoke children suites randomly.
-
test-jobs - set the maximum number of concurrent jobs allowed. See
$.test-jobs. -
job-timeout - set the timeout awaiting for jobs to complete. See
$.job-timeout.
One of the only two test tools provided by the core itself. See method setup-from-plan for the profile keys allowed.
When plan is invoked with positional integer parameter, this is equivalent to setting tests plan profile key. In either case, if tests are planned the method reports it by emitting Event::Plan.
If plan profile contains unknown keys then diagnostic event with a warning is emitted for each unknwon key.
Just invokes finish method.
Similar to done-testing but also interrupts current test suite. If it happens to be the top-suite then exits.
This tool is helpful to avoid constructs like:
if !ok($my-check-result, "...") {
skip-rest "other tests make no sense now";
}
else {
... # Do all other tests
}Such approach could be especially annoying if other tests also have a case where failure must skip remaining tests. Instead one can do:
if !ok($my-check-result, "...") {
skip-rest "other tests make no sense now";
abort-testing
}
... # Do more tests
if !ok($my-other-check, "...") {
skip-rest "makes no sense to proceed";
abort-testing
}
... # Do the restCreates a child suite. %c is used to pass parameters to the suite constructor method.
Invokes a suite as a new job. The invocation method chosen depending on the suite parallel and random attributes and this method parameters. The parameters take precedence over the attributes:
-
$instant- start job instantly, ignore the value ofrandom. -
$async- start job asynchronously always. Ifrandomis in effect then job is postponed but then would start asynchronously anyway, not matter ofparallel. -
$args– aCapturewhich will be used to call$suite's code.
The method returns job Promise of the invoked suite.
Execute the suite here and now. Internal implementation detail.
Throws a Type::Async::X exception. %c is used as exception constructor profile to which hub named parameter is added.
Results in quick suite shutdown via bypassing all remaining suite code and invoking method dismiss.
Sends a command message event. The c capture is passed with the event object and is used as parameters of the command handling method.
multi send-test(Event::Test:U \evType, Str:D $message, TestResult:D $test-result, *%event-profile -- Bool:D)>
multi send-test(Event::Test:U \evType, Str:D $message, TestResult:D $test-result, %event-profile, Bool :$bypass-todo -- Bool:D)>
Creates an event of type evType and emits it. This is the method to be used for emitting Event::Test.
send-test does the following:
-
counts tests, including total runs and failures
-
marks a test as TODO unless
:bypass-todoargument is given (seetake-TODOmethod) -
sets test number
-
sets event's
callerattribute
Emits Event::Plan event. If $on-start is True and suite is the topmost one with skip-all passed in plan profile – in other words, if topmost suite is planned for skipping; – then instead of emitting the event by standard means, hands it over directly to report-event method and instantly exits the program with 0 exit code.
Takes a free-form message possibly passed in in many chunks, splits it into lines and appends a new line to each individual line. This is the normal form of a message. Test::Async::Reporter::TAP expects children suite messages to come in normalized form.
NOTE. This form is chosen as normal because TAP is a line-based protocol for which a line must end with a newline.
This method takes a message, normalizes it, and then choses which output channel it is to be directed to:
= if suite is not the topmost one and it its $.is-async is True then message is collected in @.messages to be later passed to the parent suite with a test event. = otherwise the message is passed to method-to-console method.
This is the main method to emit a test event depending on test outcome passed in $cond or $result.cond. The method sets event origin to the invoking object, sets event's object @.messages and $.nesting. %event-profile is what the user wants to pass to Event::Test constructor. %c capture is bypassed to send-test method as-is.
Returns the next available test number. This is the number one sees next to test outcome status:
ok 2 - message
^
+--- this is it!
If suit has a TODO in effect, i.e. $.is-TODO is True or $!TODO-count is greater than 0, then this method will return the current $.TODO-message. The $.TODO-count will be reduced if necessary.
Emits Event::Cmd::SetTODO.
It's almost no-op method call with a side effect of making sure that all events emitted prior to this method call are processed. The method works by emitting Event::Cmd::SyncEvents with a Promise::Vow parameter and awaits until cmd-syncevents command handler keeps the vow. Because events are queued, this ensures that by the moment when the vow is kept all earlier events in the queue were pulled and handled.
This method implements two tasks:
-
first, it pulls postponed jobs and invokes them in a random order
-
next it calls
await-all-jobsto make sure all jobs have completed -
if
await-all-jobsdoesn't finish in 30 secondsTest::Async::X::AwaitTimeoutis thrown
This is the finalizing method. When suite ends, it invokes this method to take care of postponed jobs, report a plan if not reported at suite start (i.e. number of planned tests wasn't set), and emits Event::DoneTesting and Event::Terminate.
While performing these steps the method transition from TSFinishing stage, to TSFinished, and then calls method dismiss.
With :now the method ignores any postponed job and proceeds as if none were started. This is a kind of an emergency hatch for cases where we have good reasons to suspect a stuck job.
Transition suite to TSDismissed stage and emits Event::Terminate. After that it awaits for the event to be handled by the event loop.
This method is for the future implementation and doesn't really do anything useful now.
Produces a sequence of '&tool-name' = &tool-code> pairs suitable for use with sub EXPORT. Internal implementation detail.
Finds the context in which the current test tool is invoked and returns a Test::Async::Hub::ToolCallerCtx instance or a Failure in case of an error.
$pre-skip defines the number of frames to be skipped before the method starts looking for the real call location. The value must be relative to the frame where the method is called.
Pushes a new call location on tool call stack.
Pops a call location from tool call stack. Returns Failure if the stack is empty.
Returns the topmost call location on the tool call stack or a Failure if the stack is empty.
This method makes sure that a test tool is invoked in Test::Async::JobMgr environment. Normaly it is expected that tools are called from within threads created by the job manager. But sometimes this condition cannot be fulfilled. For example:
$object.method-returns-promise.then: -> $p { is $p.result, $expected, "promise completed as expected" };then code here is likely to be invoked in a thread created elsewhere without a chance for us to take over the process. This method wraps a test tool code into a job if it detects that the current thread is different from the suite's thread and there is not $*TEST-SUITE variable which is always set for us by the job manager.
This method sets anchor location (see Type::Async::Manual Call Location And Anchoring section) for all nested test suits or calls to test tools, done within &code. For example:
method my-compound-tool(...) is test-tool(:!wrap) {
self.anchor: {
subtest "compound subtest", :hidden, {
my-other-compound-tool(...);
}
}
}In the example the subtest and any nested tools/suits used by my-other-compound-tool will report the location where my-compound-tool is called.
Quickly create a temporary file and populate it with $data. Returns absolute file name. Throws Test::Async::X::FileCreate/Test::Async::X::FileClose in case of errors.
(c) 2020-2023, Vadim Belman [email protected]
Artistic License 2.0
See the LICENSE file in this dis