Tests cases specification

.github/workflows/Build-test-spec.yml

@@ -0,0 +1,29 @@
+name: Build TREE tests spec
+on:
+  workflow_dispatch: {}
+  pull_request: {}
+  push:
+    branches: [master]
+jobs:
+  main:
+    name: Build, Validate and Deploy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: w3c/spec-prod@v2
+        with:
+          TOOLCHAIN: bikeshed
+
+          # Modify as appropriate
+          GH_PAGES_BRANCH: gh-pages
+
+          # if your doc isn’t in the root folder,
+          # or Bikeshed otherwise can’t find it:
+          SOURCE: 04-tests.bs
+
+          # output filename defaults to your input
+          # with .html extension instead,
+          # but if you want to customize it:
+          DESTINATION: tests.html

04-tests.bs

@@ -0,0 +1,302 @@
+<pre class='metadata'>
+Title: TREE Test Specification
+Shortname: tests
+Level: 1
+Status: w3c/CG-DRAFT
+Markup Shorthands: markdown yes
+URL: https://w3id.org/tree/specification/tests
+Repository: https://github.com/treecg/specification
+Mailing List: public-treecg@w3.org
+Mailing List Archives: https://lists.w3.org/Archives/Public/public-treecg/
+Editor:
+  - Pieter Colpaert, https://pietercolpaert.be
+  - Xueying Deng, https://xdxxxdx.github.io/
+Abstract: The TREE test specification aims to provide resource that for a TREE implementation to be able to test itself against the TREE specification.This test specification will be continuously updated to align with changes and improvements in the TREE specification.
+</pre>
+# Overview # {#overview}
+
+This document outlines the minimum conformance requirements from the TREE specification and provides corresponding test cases to verify the compliance.
+This document is intended for TREE client service implementations. When processing a TREE structure, a TREE client service should be able to validate or fulfill the conformance points described in this document.
+
+<!-- (#ToBeDecided) The test specification focuses on TREE client behaviors. -->
+
+# Conformance Points # {#conformance-points}
+
+The conformance points in this document are based on the [TREE specification](https://w3c.github.io/treecg/specification/).
+
+TREE conformance is designed for HTTP-based implementations; all test cases are expected to be executed over HTTP(s), and results are determined from the HTTP(s) responses. Since TREE is an RDF (Resource Description Framework) specification, all response payloads must use standard RDF serialization formats, such as Turtle, RDF/XML, or JSON-LD.
+
+
+<!-- (#ToBeDecided) Maybe we should only keep must? to keep minimum implementation requirements -->
+
+<!-- (#ToBeDecided) The conformance of the TREE contains only two parts, the basic elements of a single nodes, and how these nodes are linked (search tree) -->
+
+## TREE basic elements ## {#1.1}
+
+### Subject of `tree:view` must be a `tree:Collection` ### {#1.1.1}
+**Description:** When there is a `tree:view` in the payload of the current HTTP(s) response, the subject of the `tree:view` must be a `tree:Collection`
+
+**SHACL shape against the HTTP(s) response:** 
+```turtle
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix tree: <https://w3id.org/tree#> .
+
+tree:ViewSubjectConstraintShape
+    a sh:NodeShape ;
+    sh:targetSubjectsOf tree:view ;
+    sh:class tree:Collection ;
+    sh:message "Subject of tree:view must be a tree:Collection" .
+
+```
+### Subject of `tree:member` must be either a `tree:Collection` or a `tree:RootNode` ### {#1.1.2}
+**Description:** If a `tree:member` property appears in the payload of the current HTTP(s) response, its subject MUST be either a `tree:Collection` or a `tree:RootNode`.
+
+**SHACL shape against the HTTP(s) response:** 
+```turtle
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix tree: <https://w3id.org/tree#> .
+
+tree:MemberSubjectConstraintShape
+    a sh:NodeShape ;
+    sh:targetSubjectsOf tree:member ;
+    sh:or (
+        [ sh:class tree:Collection ]
+        [ sh:class tree:RootNode ]
+    ) ;
+    sh:message "Subject of tree:member must be either a tree:Collection or a tree:RootNode" .
+
+```
+### `tree:Relation` properties ### {#1.1.3}
+
+**Description:** If a `tree:Relation` appears in the payload of the current HTTP(s) response, it MUST have a `tree:path` property and a `tree:node` property which pointing to another `tree:Node`.  
+    `tree:Relation` is a superclass for all TREE-supported relation types (such as `tree:GreaterThanRelation`, `tree:LessThanRelation`, `tree:GreaterThanOrEqualToRelation`, etc.).  
+    For the complete list of subclasses of `tree:Relation`, see [tree.ttl](https://github.com/TREEcg/specification/blob/master/tree.ttl).
+
+**SHACL shape against the HTTP(s) response:** 
+```turtle
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix tree: <https://w3id.org/tree#> .
+
+tree:RelationConstraintShape
+    a sh:NodeShape ;
+    sh:targetClass tree:Relation ;
+    sh:property [
+        sh:path tree:path ;
+        sh:minCount 1 ;
+        sh:message "tree:Relation must have a tree:path property"
+    ] ;
+    sh:property [
+        sh:path tree:node ;
+        sh:minCount 1 ;
+        sh:class tree:Node ;
+        sh:message "tree:Relation must have a tree:node property pointing to a tree:Node"
+    ] .
+```
+
+### Initialization of TREE structure via `tree:view` after dereferencing ### {#1.1.4}
+**Description:** When a `tree:view` triple exists in the payload of the final HTTP(s) response (after following all redirects), the final IRI MUST be the object of a `tree:view` triple whose subject is a `tree:Collection`. 
+
+**SHACL shape against the HTTP(s) response:**
+
+```turtle
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix tree: <https://w3id.org/tree#> .
+
+tree:ViewObjectConstraintShape
+    a sh:NodeShape ;
+    sh:targetObjectsOf tree:view ;
+    sh:sparql [
+        sh:select """
+            SELECT $this
+            WHERE {
+                ?collection a tree:Collection .
+                ?collection tree:view $this .
+            }
+        """ ;
+        sh:message "The final IRI must be the object of a tree:view triple whose subject is a tree:Collection"
+    ] .
+```
+## Search TREE ##  {#1.2}
+
+### `tree:Node` inbound link uniqueness ### {#1.2.1}
+**Description:** During traversal of the TREE structure, each `tree:Node` MUST NOT be the target of more than one inbound `tree:Relation` (i.e., via the `tree:node` property) from a different `tree:Node`. In other words, no `tree:Node` should have more than one parent node. This requirement ensures that the TREE remains a valid tree structure, where each node has at most one parent.
+
+**SHACL shape against the RDF graph:**
+
+```turtle
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix tree: <https://w3id.org/tree#> .
+@prefix ex: <http://example.org/> .
+
+ex:NodeInboundUniquenessShape
+    a sh:NodeShape ;
+    sh:targetClass tree:Node ;
+    sh:sparql [
+        a sh:SPARQLConstraint ;
+        sh:message "Each tree:Node must not be the target of more than one tree:Relation, tree:node link from another node." ;
+        sh:select """
+            SELECT ?this (COUNT(?sourceNode) AS ?inboundCount)
+            WHERE {
+                ?sourceNode tree:relation ?relation .
+                ?relation tree:node ?this .
+                FILTER (?sourceNode != ?this)
+            }
+            GROUP BY ?this
+            HAVING (COUNT(?sourceNode) > 1)
+        """ ;
+    ] .
+
+````
+### `tree:GreaterThanRelation` ### {#1.2.2}
+**Description:** When traversing a TREE structure by following `tree:Relation` links (after making one or more HTTP(s) requests and aggregating the resulting RDF graphs), if a `tree:GreaterThanRelation` is present, then for each member referenced by the relation, the value of the property specified by `tree:path` MUST be greater than the value specified in the relation, according to the comparison rules defined in the [SPARQL algebra functions](https://www.w3.org/TR/sparql11-query/#expressions). This ensures that the `tree:GreaterThanRelation` accurately represents a "greater than" relationship as defined by SPARQL semantics.
+
+
+### `xsd:dateTime` literals without a timezone comparisons  ### {#1.2.3}
+**Description:** When traversing a TREE structure, if an implementation employs `xsd:dateTime` literals without an explicit timezone, it MUST treat these values as representing the entire range from that date and time at UTC-14:00 (inclusive) to UTC+14:00 (exclusive). Comparisons involving such `xsd:dateTime` values MUST be performed as interval comparisons: a value without a timezone matches if and only if the comparison holds for at least one instant within this interval. Implementations MUST NOT assume any default timezone or offset for such values.
+
+
+
+<!-- 
+// Initial version
+// TODO
+
+// # Tests # {#tests}
+
+// In the test snippets below, the URL will always be relative. You can decide your own base IRI for all of the HTTP requests and relative IRIs in your test framework.
+
+
+// ### Initialization ###  {#1}
+
+// Purpose: Ensuring that there is an unambiguous yet user friendly way of knowing the identifier of the collection, as well as the current page of the collection’s view.
+
+// This test is about a function `initialization(url)`. The function will return the URL of the collection and the URL of the root node.
+
+// We will test this with various URLs containing different contents.
+
+// #### The URL to a root node without redirects #### {#1.1}
+
+// **Test:** Initializing with the URL to a root node without redirects returns the Collection URL and Root node URL.
+
+// File URL `test1.1.ttl`.
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <Collection> tree:view <test1.1.ttl> .
+// ```
+
+// The test executes an HTTP request to `test1.1.ttl`. The algorithm returns:
+//  * Collection: `<Collection>`
+//  * Root node: `<test1.1.ttl>`
+
+// #### The URL to a collection without redirects #### {#1.2}
+
+// **Test:** Initializing with the URL to a collection IRI without redirects returns the Collection IRI and root node URL.
+
+// Contents of the file `test1.2.ttl`:
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <test1.2.ttl#Collection> tree:view <test1.2.ttl> .
+// ```
+
+// The test executes an HTTP request to `test1.2.ttl#Collection`. The algorithm returns:
+//  * Collection: `<test1.2.ttl#Collection>`
+//  * Root node: `<test1.2.ttl>`
+
+// #### The URL to a root node before redirects #### {#1.3}
+
+// **Test:** Initializing with the URL to a collection IRI that results in a redirect, still returns the Collection IRI and root node URL.
+
+// File url `test1.3` that provides a `303 See Other` redirect to `test1.3.ttl`.
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <Collection> tree:view <test1.3.ttl> .
+// ```
+
+// The test executes an HTTP request to `test1.3`. The algorithm returns:
+//  * Collection: `<Collection>`
+//  * Root node: `<test1.3.ttl>`
+
+// The same test MUST be repeated with a `301` response code.
+
+// #### The URL that does not match #### {#1.4}
+
+// **Test:** Initializing with a URL that does not match a collection or a root node must result into an exception.
+
+// File url `test1.4.ttl`:
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <Collection> tree:view <test1.4.ttl> .
+// ```
+
+// The test executes an HTTP request to `test1.4.ttl#NonExistingNodeOrCollection`. The algorithm returns an exception that indicates the requested root node or collection is not described in the response.
+
+// #### Search Forms #### {#1.x}
+
+// This is yet to be defined: the search forms should also be extracted.
+
+// ### Members ## {#2}
+
+// Goal: Once we have the container URL, we must ensure we know what the members of the collection mentioned in this page are.
+
+// #### Finding member IRIs #### {#2.1}
+
+// **Test:** Finding both named node and blank node member terms in a page.
+
+// File url `<test2.1.ttl>` contains:
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <Collection> tree:view <test2.1.ttl> ;
+// 	tree:member <A>, <B>, _:b0 .
+// ```
+
+// The test suite executes the function to find all member identifiers in the page `<test2.1.ttl>` of the collection `<Collection>` and returns 2 member identifiers `<A>`, `<B>` and a blank node member.
+
+// #### Empty page #### {#2.2}
+
+// **Test:** Finding no member terms in a page when there are none.
+
+// File url `<test2.2.ttl>`
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// <Collection> tree:view <test2.2.ttl> .
+// ```
+// The test to find the set of members in the page `<test2.2.ttl>` of the collection `<Collection>` returns an empty set.
+
+// ### Extracting members ### {#3}
+
+// Goal: Checking whether your implementation will extract the right set of quads
+
+
+// #### Star pattern #### {#3.1}
+
+// **Test:** Finding all quads that belong to a member based on a simple star pattern.
+
+// File url `<test3.1.ttl>`
+
+// Operation: Finding all quads that belong to `<A>`.
+
+// ```turtle
+// @prefix tree: <https://w3id.org/tree#> .
+// @prefix ex: <https://example.org/>.
+// <Collection> tree:view <test3.1.ttl> ;
+// 	tree:member <A> .
+// <A> ex:p ex:o .
+// ```
+
+// Returns: an array with 1 quad `<A> ex:p ex:o`.
+
+// TODO: take more tests from the [extract cbd shape repository](https://github.com/TREEcg/extract-cbd-shape)
+
+// ### Pruning relations ### {#4}
+
+// TODO: These test cases will get more complex
+
+// ### Using search forms ### {#5}
+
+// TODO: Search forms
+-->