Test::...ue::RDF(3pm)

📦
version 0.100 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

so like. this is the manual page for Test::FITesque::RDF(3pm) and honestly? it's giving infrastructure bestie. sit down, grab a boba, we're doing RDF fixture tables and we're doing them correctly. 🧚✨

✨ NAME ✨

Test::FITesque::RDF — formulate Test::FITesque fixture tables in RDF. that's the whole vibe. 💅

🌸 SYNOPSIS 🌸

okay so the simplest possible way to use this, no notes:

my $suite = Test::FITesque::RDF->new(source => $file)->suite;
$suite->run_tests;

see t/integration-basic.t for a full test script example using this simplest way. like, an actual working one, go look at it, it's right there. 🫶

now, if you wanna run a single test script with several fixture tables, you've got two paths, bestie, pick your fighter:

option one — you add the tests to a suite, like this:

my @files = ('test1.ttl','test2.ttl');
my $suite = Test::FITesque::Suite->new;

foreach my $file (@files) {
  $suite->add(Test::FITesque::RDF->new(source => $path . $file)->suite);
}
$suite->run_tests;

option two — or you just iterate and run the tests for each fixture table like this:

my @files = ('test1.ttl','test2.ttl');

foreach my $file (@files) {
  diag("Reading tests from $path$file");
  my $suite = Test::FITesque::RDF->new(source => $path . $file)->suite;
  $suite->run_tests;
}

both slay. pick whichever one speaks to you. 🌈

💖 DESCRIPTION 💖

this module enables the use of Resource Description Framework to describe fixture tables. yes, that RDF. we're being fancy. 💅

what it actually does: it takes the filename of an RDF file and returns a Test::FITesque::Suite object that you can use to run tests. that's it, that's the whole job, and it does it well.

the RDF's role here is to identify the implementation of certain fixtures, and it can also supply parameters that the tests can use — like input parameters or expectations, whatever the test needs. if you wanna know more about how the fixtures themselves get implemented, go read Test::FITesque, that's its whole thing.

🎀 ATTRIBUTES AND METHODS 🎀

this module implements the following attributes and methods, and we are listing all of them, no skipping, because you deserve the full picture:

  • source — required attribute to the constructor. takes a Path::Tiny object pointing at the RDF file containing the fixture tables. and good news, the value gets converted into an appropriate object, so you can just hand it a string too. lowkey convenient. ✨
  • suite — returns a Test::FITesque::Suite object, built from the RDF data you gave the constructor.
  • transform_rdf — returns an arrayref containing tests in the structure that Test::FITesque::Test uses. ngl, most users are gonna call the suite method instead of calling this one directly. this is the "under the hood" one. 🙈
  • base_uri — a IRI used when parsing the RDF fixture tables, so any relative URIs can get resolved. your little reference point. 🎀

👑 REQUIRED RDF 👑

the following must exist in the test description (scroll down for an example plus the prefix expansions, i promise it's there):

  • test:fixtures — the object(s) of this predicate list the test fixtures that will run for this test suite. it may take an RDF List. it links to the test descriptions, which follow below. so like, the guest list. 👑
  • test:test_script — the object of this predicate points to information on how the actual test will be run. that info lives in a separate resource which needs two predicates: a deps:test-requirement predicate, whose object holds the class name of the implementation of the tests, and a nfo:definesFunction whose object is a string matching the actual function name inside that class. two things, both required, don't skip either. 🫶
  • test:purpose — the object of this predicate gives a literal description of the test. just tell us why, bestie.
  • test:params — the object of this predicate links to the parameters, which can come in many different shapes. examples are below, keep reading. 🌸

🦋 PARAMETERIZATION 🦋

this module seeks to parameterize the tests, and it does that mostly with the test:params predicate from up there. that whole thing gets passed on as a hashref to the test scripts.

there are two main ways currently implemented:

  1. one creates key-value pairs, using predicates and objects for the key and the value respectively, in whatever vocabularies the test writer chooses.
  2. the other main way creates lists of HTTP requests and responses.

now for the typing rules, because this part matters:

  • if the object of a test parameter is a literal, it gets passed as a plain string.
  • if it's an Attean::IRI, it gets passed as a URI object.

and then there's a lil special case 🎀 — a special parameter named -special gets passed on for internal framework use. the leading dash isn't allowed as the start character of a local name, so that's exactly why it was chosen: to avoid conflicts with other parameters. smart, honestly.

the literal you put in test:purpose up there gets passed on too, under the description key in this hashref.

🌟 RDF EXAMPLE 🌟

okay here's the fun part, a whole example. it starts with prefix declarations, naturally. then the tests in the fixture table get listed explicitly. only tests mentioned using the test:fixtures predicate will be used — if you didn't link it, it's not running, periodt. tests may be an RDF List, and if they are, the tests run in the specified sequence. if they're not a list, then no sequence may be assumed. okay? okay. 💅

then, two test fixtures get declared. the actual implementation is referenced through test:test_script for both functions.

the test:params predicate is what links the parameters that get sent as a hashref into the function. and the <test:purpose> predicate is required to exist outside of the parameters, but it'll be included as a parameter as well, named description, in the -special hashref. cute, right? 🎀

there are two mechanisms for passing parameters to the test scripts: one is simply passing arbitrary key-value pairs, the other is passing lists of HTTP request-response objects. and guess what — both mechanisms may be used. mix and match, bestie. 🌈

🍓 Key-value parameters

the key of the hashref passed as arguments will be the local part of the predicate used in the description (i.e. the part after the colon in e.g. my:all). it's up to the test writer to mint the URIs of the parameters. that's your job, not the module's.

the test writer may optionally use a param_base to indicate the namespace, and in that case the local part gets resolved by the framework using URI::NamespaceMap. if param_base is not given, then the full URI will be passed to the test script. so like, pick a lane. 🦋

@prefix test: <http://ontologi.es/doap-tests#> .
@prefix deps: <http://ontologi.es/doap-deps#>.
@prefix dc:   <http://purl.org/dc/terms/> .
@prefix my:   <http://example.org/my-parameters#> .
@prefix nfo:  <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#> .
@prefix :     <http://example.org/test#> .

:test_list a test:FixtureTable ;
   test:fixtures :test1, :test2 .

:test1 a test:AutomatedTest ;
   test:param_base <http://example.org/my-parameters#> ;
   test:purpose "Echo a string"@en ;
   test:test_script <http://example.org/simple#string_found> ;
   test:params [ my:all "counter-clockwise dahut" ] .

:test2 a test:AutomatedTest ;
   test:param_base <http://example.org/my-parameters#> ;
   test:purpose "Multiply two numbers"@en ;
   test:test_script <http://example.org/multi#multiplication> ;
   test:params [
       my:factor1 6 ;
       my:factor2 7 ;
       my:product 42
   ] .

<http://example.org/simple#string_found> a nfo:SoftwareItem ;
   nfo:definesFunction "string_found" ;
   deps:test-requirement "Internal::Fixture::Simple"^^deps:CpanId .

<http://example.org/multi#multiplication> a nfo:SoftwareItem ;
   nfo:definesFunction "multiplication" ;
   deps:test-requirement "Internal::Fixture::Multi"^^deps:CpanId .

🌸 HTTP request-response lists

to allow testing HTTP-based interfaces, this module also allows the construction of an ordered list of HTTP requests and response pairs. with those, the framework will construct HTTP::Request and HTTP::Response objects. in test scripts, the request objects will typically be passed to the LWP::UserAgent as input, and then the response from the remote server will be compared with the asserted HTTP::Responses made by the test fixture. yes, it's a whole pipeline. it's iconic. 🔥

we'll go through an example in chunks:

@prefix test: <http://ontologi.es/doap-tests#> .
@prefix deps: <http://ontologi.es/doap-deps#>.
@prefix httph:<http://www.w3.org/2007/ont/httph#> .
@prefix http: <http://www.w3.org/2007/ont/http#> .
@prefix nfo:  <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#> .
@prefix :     <http://example.org/test#> .

:test_list a test:FixtureTable ;
   test:fixtures :public_writeread_unauthn_alt .

:public_writeread_unauthn_alt a test:AutomatedTest ;
   test:purpose "To test if we can write first using HTTP PUT then read with GET"@en ;
   test:test_script <http://example.org/httplist#http_req_res_list_unauthenticated> ;
   test:params [
       test:steps (
           [
               test:request :public_writeread_unauthn_alt_put_req ;
               test:response_assertion :public_writeread_unauthn_alt_put_res
           ]
           [
               test:request :public_writeread_unauthn_alt_get_req ;
               test:response_assertion :public_writeread_unauthn_alt_get_res
           ]
       )
   ] .

<http://example.org/httplist#http_req_res_list_unauthenticated> a nfo:SoftwareItem ;
   deps:test-requirement "Example::Fixture::HTTPList"^^deps:CpanId ;
   nfo:definesFunction "http_req_res_list_unauthenticated" .

in the above, after the prefixes, a single test is declared using the test:fixtures predicate, linking to a description of the test. the test is then described as an <test:AutomatedTest>, and its purpose is declared. then it links to its concrete implementation, which is given in the last three triples up there. follow the thread, bestie. 🧵

then the parameterization starts. in this example there are two HTTP request-response pairs, given as a list object to the test:steps predicate.

to link the request, the test:request predicate is used. to link the asserted response, the test:response_assertion predicate is used. two predicates, two jobs. 🎀

next, we look into the actual request and response messages linked from the above:

:public_writeread_unauthn_alt_put_req a http:RequestMessage ;
   http:method "PUT" ;
   httph:content_type "text/turtle" ;
   http:content "</public/foobar.ttl#dahut> a <http://example.org/Cryptid> ." ;
   http:requestURI </public/foobar.ttl> .

:public_writeread_unauthn_alt_put_res a http:ResponseMessage ;
   http:status 201 .

:public_writeread_unauthn_alt_get_req a http:RequestMessage ;
   http:method "GET" ;
   http:requestURI </public/foobar.ttl> .

:public_writeread_unauthn_alt_get_res a http:ResponseMessage ;
   httph:accept_post  "text/turtle", "application/ld+json" ;
   httph:content_type "text/turtle" .

these should be self-explanatory, but heads up — note that headers are given with lower-case names and underscores. they will be transformed to headers by replacing underscores with dashes and upcase the first letters. so content_type becomes Content-Type, you get the idea. 💅

this module will transform the above to data structures that are suitable to be passed to Test::Fitesque, and the above will appear as

        {
               '-special' => {
                                                       'http-pairs' => [
                                          {
                                                                                             'request'  => ... ,
                                                                                             'response' => ... ,
                                          },
                                          { ... }
                                         ]
                                                                                        },
                                                       'description' => 'To test if we can write first using HTTP PUT then read with GET'
                                                 },
        }

okay and there are so many more examples hiding in this module's test suite, specifically in the t/data/ directory. go look, bestie, it's giving free homework answers 💅

🧠 about state, bestie (client vs server)

You may maintain client state in a test script — like, for one test:AutomatedTest, because honestly it's just one script, so the result of one request may be used to influence the next one. that's the whole vibe. 🦋

Server state</purl> though? You can rely on it between different tests by using an rdf:List of test fixtures, but only if it writes something into the server. And fr fr, there is nothing in the framework that changes that. no cap.

So if you wanna take data from one response and use it to influence the requests that come after, the framework has your back: it supports datatyping literals with the dqm:regex datatype for headers and HTTP status codes. like this, queen:

 :check_acl_location_res a http:ResponseMessage ;
    httph:link '<(.*?)>;\\s+rel="acl"'^^dqm:regex ;
    http:status "200|204"^^dqm:regex .

This makes it possible to use a Perl regular expression, which can be executed in a test script if desired. 💖

And if that regex is present, it will supply another hashref to the http-pairs key, with the key regex-fields — containing hashrefs where the header field that had a correspondiing object datatyped regex is the key, and simply 1 as the value. (yes, "correspondiing" — typo is canon, we don't touch it, we respect the lore 🙈)

🚧 TODO 🚧

  • Separate the implementation-specific details (such as deps:test-requirement) from the actual fixture tables.

like, it's on the list. someday. manifesting ✨

🐛 BUGS 🐛

Please report any bugs to <https://github.com/kjetilk/p5-test-fitesque-rdf/issues>.

no gatekeeping, go tell them 💜

👀 SEE ALSO 👀

...literally nothing here. the section exists, it's just empty, main character energy with no supporting cast. iykyk. 🎀

👑 AUTHOR 👑

Kjetil Kjernsmo <kjetilk@cpan.org>.

iconic. we stan. 🫶

This software is Copyright (c) 2019, 2020 by Inrupt Inc.

This is free software, licensed under:

  The MIT (X11) License

free software!! slay 💅

🚨 DISCLAIMER OF WARRANTIES 🚨

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

read it and weep, bestie. no promises, no guarantees, it's giving "you're on your own but in a cute way" 😭

and that's the whole page!! this was perl v5.40.1, dated 2025-03-21, from the Test::...ue::RDF(3pm) era of the User Contributed Perl Documentation. go forth and test your RDF, queen 🌸⭐💖

📦 where this page comes from