para

head

Reusable conformance ("contract") tests for L<Qwiratry> location plugins.


A location plugin provides C<Qwiratry::Location::<NAME>::Source> and/or
C<Qwiratry::Location::<NAME>::Destination> classes that inherit the contracts in
L<Qwiratry::Location::Base>. This module asserts, from the outside, that such a
plugin satisfies the shared contract: it is discoverable through the factory,
its operation classes inherit the correct base, its URI scheme resolves to the
backend, it round-trips (when writable and readable), reports missing locations
as C<X::Qwiratry::IO::LocationError>, and works through the C<⮳> / C<⮷>
pipeline operators.


code

=begin code
use Test;
use Qwiratry::Test::Location;

my $tmp = $*TMPDIR.add("qwiratry-{$*PID}.txt").absolute;

conforms-to-location-contract(
    backend             => 'File',
    scheme              => 'file',
    sample-location     => $tmp,
    roundtrip-location  => $tmp,
    missing-location    => $*TMPDIR.add("does-not-exist-{$*PID}").absolute,
);

done-testing;
=end code


Network-backed backends should pass C<:needs-network>; those subtests are
skipped unless C<QWIRATRY_TEST_NETWORK> is set, so plugin CI stays hermetic by
default.


C<RAKUDO_RAKUAST=1> (inherited from Qwiratry's slang).



unit module Qwiratry::Test::Location;

use Test;
use Qwiratry::Location;
use Qwiratry::Location::Base;
use Qwiratry::Query::Slang;
use X::Qwiratry;

#| Assert that the named location backend satisfies the Qwiratry location contract.
#|
#| Capability flags/arguments (all optional except C<:backend>):
#|   :readable / :writable   which operations the backend supports (default: both)
#|   :scheme                 URI scheme that must resolve to this backend
#|   :sample-location        a location string the backend recognises (for factory checks)
#|   :roundtrip-location     writable+readable target: write then read must match
#|   :roundtrip-content      the payload used for the round-trip (default provided)
#|   :missing-location       readable: reading it must throw X::Qwiratry::IO::LocationError
#|   :needs-network          gate live subtests behind the QWIRATRY_TEST_NETWORK env var
#|   :pipeline               also exercise the ⮳ / ⮷ operators (default: True)
sub conforms-to-location-contract(
    Str  :$backend!,
    Bool :$readable = True,
    Bool :$writable = True,
    Str  :$scheme,
    Str  :$sample-location,
    Str  :$roundtrip-location,
    Str  :$roundtrip-content = 'qwiratry-conformance-payload',
    Str  :$missing-location,
    Bool :$needs-network = False,
    Bool :$pipeline = True,
    Str  :$desc = "Qwiratry::Location '$backend' contract",
    --> Bool
) is export {
    # Discovery/factory/scheme checks are offline; only the round-trip and
    # missing-location checks actually touch the backend, so gate just those
    # behind the network opt-in.
    my $live-ok = !$needs-network || ?%*ENV<QWIRATRY_TEST_NETWORK>;
    my $probe = $sample-location // $roundtrip-location // $missing-location;

    subtest $desc => {
        if $readable {
            subtest 'source: discovery, factory, base contract' => {
                ok $backend.lc (elem) Qwiratry::Location.backends(:type<Source>)».lc,
                    "'$backend' is discoverable as a Source backend";
                if $probe.defined {
                    my $impl = Qwiratry::Location.make(:type<Source>, :location($probe));
                    isa-ok $impl, Qwiratry::Location::Base::Source,
                        "Source impl inherits Qwiratry::Location::Base::Source";
                    can-ok $impl, 'read', 'Source impl provides a read method';
                }
                else {
                    skip 'no :sample-location/:roundtrip-location/:missing-location given', 2;
                }
            }
        }

        if $writable {
            subtest 'destination: discovery, factory, base contract' => {
                ok $backend.lc (elem) Qwiratry::Location.backends(:type<Destination>)».lc,
                    "'$backend' is discoverable as a Destination backend";
                if $probe.defined {
                    my $impl = Qwiratry::Location.make(:type<Destination>, :location($probe));
                    isa-ok $impl, Qwiratry::Location::Base::Destination,
                        "Destination impl inherits Qwiratry::Location::Base::Destination";
                    can-ok $impl, 'write', 'Destination impl provides a write method';
                }
                else {
                    skip 'no :sample-location/:roundtrip-location/:missing-location given', 2;
                }
            }
        }

        if $scheme.defined {
            subtest "scheme: '$scheme' resolves to '$backend'" => {
                is Qwiratry::Location.backend-name-for-scheme($scheme).lc, $backend.lc,
                    "scheme '$scheme' resolves to backend '$backend'";
                if $probe.defined && $probe.contains('://') {
                    is Qwiratry::Location.backend-name-from-location($probe).lc, $backend.lc,
                        "location '$probe' resolves to backend '$backend'";
                }
            }
        }

        if $writable && $readable && $roundtrip-location.defined && !$live-ok {
            skip 'round-trip needs network (set QWIRATRY_TEST_NETWORK to run)';
        }
        elsif $writable && $readable && $roundtrip-location.defined {
            subtest 'round-trip: write then read returns the same content' => {
                my $sink = Qwiratry::Location.make(:type<Destination>, :location($roundtrip-location));
                my $source = Qwiratry::Location.make(:type<Source>, :location($roundtrip-location));

                my $returned = $sink.write($roundtrip-location, $roundtrip-content);
                is $returned, $roundtrip-content,
                    'write returns the original content for pass-through';
                is $source.read($roundtrip-location), $roundtrip-content,
                    'read returns the previously written content';

                if $pipeline {
                    my $payload = $roundtrip-content ~ '-via-pipeline';
                    $payload ⮷ $roundtrip-location;
                    is (⮳ $roundtrip-location), $payload,
                        '⮷ then ⮳ round-trips through the pipeline operators';
                }
            }
        }

        if $readable && $missing-location.defined && !$live-ok {
            skip 'missing-location check needs network (set QWIRATRY_TEST_NETWORK to run)';
        }
        elsif $readable && $missing-location.defined {
            subtest 'errors: reading a missing location throws LocationError' => {
                my $source = Qwiratry::Location.make(:type<Source>, :location($missing-location));
                throws-like { $source.read($missing-location) },
                    X::Qwiratry::IO::LocationError,
                    'missing location is reported as X::Qwiratry::IO::LocationError';
            }
        }
    }
}


root

README

Format

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<AI|file:../mcp/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=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<Download | file:../download/index.podlite>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>

=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>
    =item2 L<Hand these documents to an AI assistant|file:../mcp/index.podlite>

=end nested
=begin nested :!nested
=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/>

=end nested
=end React


Built with L<Podlite|https://podlite.org> — the markup and publishing tools behind this site.


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


Location

Qwiratry::Test::Location

Synopsis

Requires

Qwiratry::Test v0.0.1

Authors

License

Dependencies

Test Dependencies

Provides

Documentation