Image

head

code

root

para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

README

... unless you really know what you're doing.


B<Note> that this section is not about creating own test bundle.


L<C<Test::Async>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async.md>
itself does some backstage work when imported with C<use> or C<require>. A part of this work is taking a list of
registered bundles, fixing it, and building a L<C<Map>|https://docs.raku.org/type/Map> of exports out of it. The potential problem hides behind the
word I<fixing> because what it means is adding
L<C<Test::Async::Base>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async/Base.md>
into the list of registered bundles if no other bundles is registered yet; and adding
L<C<Test::Async::Reporter::TAP>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async/Reporter/TAP.md>
to the list if none of the registered bundles does
L<C<Test::Async::Reporter>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async/Reporter.md>
role. Say, if there is a module C<Foo> which C<use>s C<Test::Async>, and there is a suite with a header like this:


use Foo;
use MyTests;
use MyReporter;
use Test::Async;


Then we will have implicitly registered C<Test::Async::Base> and C<Test::Async::Reporter::TAP>. While not being a
problem most of the time, this could pose a risk in some unforeseen edge cases.


The recommended way is to use C<Test::Async::Hub> class C<test-suite> method which returns the current test :


use Test::Async::Hub;
sub foo {
    my $suite = Test::Async::Hub.test-suite;
    $suite.pass: "that's the way";
}


Another recommended way is shown in the first example of the next section.


One of the biggest reasons which pushed me to implement C<Test::Async> was a need to test event flow in C<Vikna>
toolkit. The problem with the standard C<Test> framework was the need to invoke test tool from inside a separate thread
or even threads causing havoc to the test output when C<subtest>s are used. Similar problem could arise for any heavily
threaded application where it is not always easy to get hold of the internal states without having direct access to them
from within of a thread. Sure, it is technically possible to implement a communication channel which could be used to
pass data into the test suit main thread, etc., etc., etc.


Nah, that's not how we do it! How about:


subtest "Threaded testing" => {
    my $test-app = MyTestApp.new( :test-suite(test-suite) );
    $test-app.test-something-threaded;
}


and then somewhere in the C<MyTestApp> class implementation, which is presumably inherits from the base application
class and overrides some of its method for testing, we simply do something like:


method foo($param) {
    $.test-suite.ok: self.is-param-valid($param), "method foo got correct parameter";
    nextsame
}


C<test-suite> attribute in this example is the suite object backing our subtest.


It is also possible not to store the suite object as an attribute. Instead, one could use
L<C<Test::Async::JobMgr>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async/JobMgr.md>
method C<start> to spawn new threads. This approach has two advantages: first, it preserves the suite object, on which
the method has been invoked, as the one available via C<test-suite>; second, it creates an awaitable job meaning that
our subtest won't finish until the job is complete:


method test-something-threaded {
    for ^10 -> $i {
        Test::Async::Hub.test-suite.start: {
            self.bar($i)
        }
    }
}
method bar($i) {
    Test::Async::Hub.test-suite.cmp-ok: $i, "<", 10, "small enough"
}
}


All outcomes of C<cmp-ok> will be reported as part of our C<subtest>.


This approach provides more flexibility because it makes it possible to simultaneously test different execution branches
of the same object:


use Test::Async;
plan 1, :parallel;
my $test-app = MyTestApp.new;
subtest "Branch 1" => {
    $test-app.test-something-threaded1;
}
subtest "Branch 2" => {
    $test-app.test-something-threaded2;
}


When both methods C«test-something-threaded<N>» are using C<test-suite.start> then both subtests will report only
related test tool outcomes.


Sometimes it might be useful to export a symbol or two from a bundle. The best way to do it is to use C<EXPORT::DEFAULT>
package defined in your bundle file:


test-bundle Test::Async::MyBundle {
    ...
}
package EXPORT::DEFAULT {
    our sub foo { "exported" }
}


The reason for doing so is because a user could consume the bundle using L<C<Test::Async>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async.md> parameters:


use Test::Async <MyBundle Base>;
say foo;


In this case L<C<Test::Async>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async.md> not only will export all found test tool methods but it would also fetch the symbols from
C<EXPORT::DEFAULT> and re-export them. Apparently, the approach allows direct consuming via C<use> statement to work
too:


use Test::Async::MyBundle;
use Test::Async::Base;
use Test::Async;
say foo;


L<C<Test::Async>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async.md>,
L<C<Test::Async::Manual>|https://github.com/vrurg/raku-Test-Async/blob/v0.0.16/docs/md/Test/Async/Manual.md>


CookBook

module Test::Assertion:ver<0.0.4>:auth<zef:lizmat> {

    # This is the "is test-assertion" trait as defined in Rakudo
    # 2020.10 and later.  It doesn't do anything else than mix in
    # a method "is-test-assertion", whose *existence* is enough to
    # mark a subroutine as a subroutine doing test assertions.
    # Add this candidate to the :TEST export class, so it doesn't
    # get exported by default.
    multi sub trait_mod:<is>(Routine:D $r, :$test-assertion!) is export(:TEST) {
        $r.^mixin( role is-test-assertion {
            method is-test-assertion(--> True) { }
        }) if $test-assertion;
    }
}

# Exporter logic loads whatever this system's Test module brings.
# If the application of the "test-assertion" trait to a subroutine
# works, this implies that this version of Test already has the
# trait, so we don't need to export anything.  Otherwise we're
# going to export what the "is export" trait put into the
# EXPORT::TEST namespace (which would be the local copy of
# the trait_mod).  Since we only need to do this at pre-compilation
# time, we save the value in a constant.
sub EXPORT() {
    use Test;

    my constant $nr-candidates = &trait_mod:<is>.candidates.grep( {
        .[0].type ~~ Routine && .[1].name eq q/$test-assertion/
          given .signature.params;
    } ).elems;

    BEGIN $nr-candidates
      ?? Map.new
      !! Map.new( EXPORT::TEST::.head )
}



provide 'is test-assertion' trait for older Rakus


=begin code :lang<raku>

use Test;
use Test::Assertion;

sub foo-test() is test-assertion {  # will never be compile-time error
    subtest "we do many tests" => {
        flunk "failed this one";    # <-- points here if doesn't work
    }
}

foo-test();  # <-- points here if test-assertion *does* work

=end code


Test::Assertion is a module that provides the C<is test-assertion> trait
for subroutines, which was introduced in Rakudo 2020.10, to older versions of
Raku.  This allows module authors to use the C<is test-assertion> trait in
a module without having to worry whether the version of Raku actually
supports that trait.


If a distribution does not use any external testing functionality, then
this module should probably be added as a dependency to the "test-depends"
section of the META information of a module, as it will (most likely) only
be needed during testing.


If this module is used by a distribution that is geared towards offering
additional testing facilities, then clearly this module must be listed in
the "depends" section.


Please note that this does B<not> actually implement the
C<is test-assertion> error reporting logic: it merely makes sure that the
use of the trait will not be a compile time error in the test-file where
it is being used.


Source can be located at: https://github.com/lizmat/Test-Assertion . Comments and
Pull Requests are welcome.


This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.


Assertion

The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


README

NAME

SYNOPSIS

DESCRIPTION

AUTHOR

COPYRIGHT AND LICENSE

Test::Assertion v0.0.4

Authors

License

Dependencies

Test Dependencies

Provides

Documentation