This application implements the GITB test service APIs in a
Spring Boot web application that is meant to support
GITB TDL test cases running in the Interoperability Test Bed.
The sample validation service validates a text against an (also provided) expected value. The user of the service can also select whether he/she wants to have a mismatch reported as an error or a warning. Finally, an information message is also returned in case values match but when ignoring casing.
Once running, the validation endpoint's WDSL is available at http://localhost:8080/services/validation?WSDL. See here for further information on processing service implementations.
This validation services requires in the validation call two parameters:
- ldes-url: the url of the LDES to validate
- shacl-shape: the shacl shape that will be used to validate the server against to
- Docker
- A complete up and running TestBed instance
- An LDI Orchestrator
- An Ontotext GraphDB instance
All these services are set up in the ./docker/docker-compose.yaml
config file, but
here are dummy environment variables used that must be changed in a production environment
- Add the TestBed Shacl Validator to
docker-compose.yaml
file
testbed-shacl-validator:
image: ghcr.io/informatievlaanderen/testbed-shacl-validator:latest
depends_on:
- <GRAPH_DB_SERVICE_NAME>
- <LDIO_WORKBENCH_SERVICE_NAME>
environment:
- LDIO_SPARQLHOST=http://<LDIO_WORKBENCH_SERVICE_NAME>:<INTERNAL_LDIO_CONTAINER_PORT>
- LDIO_SPARQLHOST=http://<GRAPH_DB_SERVICE_NAME>:<INTERNAL_GRAPHDB_CONTAINER_PORT>
- SERVER_PORT=8080
In this specific tutorial, this would result in the following config:
testbed-shacl-validator:
image: ghcr.io/informatievlaanderen/testbed-shacl-validator:latest
depends_on:
- graphdb
- ldio-workbench
environment:
- LDIO_HOST=http://ldio-workbench:8080
- LDIO_SPARQLHOST=http://graphdb:7200
- SERVER_PORT=8080
- Start up all the services
docker compose up -d --wait
- Add a test suite to TestBed that uses this service
In this step, a test suite will be written and can be written in many different ways. In this specific case, a test suite will be written that contains only one test case. This test case will prompt for a Linked Data Event Stream url, which will be validated against the provided SHACL shape.
First of all, make a folder that will contain all required files for the test suite:
mkdir validate_ldes_to_shacl_shape
cd validate_ldes_to_shacl_shape
mkdir test_cases
Secondly, test case xml file can be added to the test_cases
folder.
<testcase id="ts1_tc1" xmlns="http://www.gitb.com/tdl/v1/" xmlns:gitb="http://www.gitb.com/core/v1/">
<metadata>
<gitb:name>[TC1] Validate LDES</gitb:name>
<gitb:version>1.0</gitb:version>
<gitb:description>Validate an LDES against a specific SHACL shape</gitb:description>
</metadata>
<actors>
<gitb:actor id="LDESServer" role="SUT"/>
<gitb:actor id="SHACLValidator"/>
</actors>
<steps stopOnError="true">
<!-- Prompt the user to enter the required data to run the test -->
<interact id="validationData" desc="Setup parameters to validate the LDES">
<request desc="URL of the LDES to validate" name="ldes"/>
<request desc="Shacl shape that must be used for validating" name="shaclShape" inputType="UPLOAD"/>
</interact>
<log>"Starting shacl validation test"</log>
<!-- Step 3: Check relation timestamp consistency. -->
<!-- Notice here how we refer to the address of the validation service using the domain-level "validationServiceAddress" configuration property. -->
<verify output="validatorOutput" id="shaclValidationStep" desc="validate against shacl"
handler="http://testbed-shacl-validator:8080/services/validation?wsdl">
<input name="ldes-url">$validationData{ldes}</input>
<input name="shacl-shape">$validationData{shaclShape}</input>
</verify>
<log>"shacl verification finished"</log>
</steps>
<output>
<success>
<default>"Test session completed successfully."</default>
</success>
<failure>
<default>
"Test session failed. Please check the failed step report and the test session log for details."
</default>
</failure>
</output>
</testcase>
Some interesting things we see in this test case, are the interact
block, as well as the verify
block.
This block is responsible for prompting the user/tester to enter some data that will be used for the test. In this specific case, it will be the URL of the LDES that must be validated.
This block is responsible for the verifying the LDES by calling the external service, which is this TestBed Shacl
Validator service. The most important part to notice here is the handler
attribute, where the external TestBed Shacl
Validator service will be set. In this case, the docker compose service name must be used, followed by the port. After
that, the "fixed" uri is placed, which will call the right validation service, which is in this case
/services/validation?wsdl
Another thing that can be noticed here, are the input parameters. These two parameters are required to let the test run.
ldes-url
: the url of the LDES that must be validated. The value here is fetched from the prompted inputshacl-shape
: the SHACL shape that will be used to validate all the members against to. Here is the value also fetched from the prompted input
To finish up this step, a test suite itself must be added as well. This can be done by adding test_suite.xml
to the
validate_ldes_to_shacl_shape
folder.
This is how the file should look like:
<?xml version="1.0" encoding="UTF-8"?>
<testsuite id="ts1" xmlns="http://www.gitb.com/tdl/v1/"
xmlns:gitb="http://www.gitb.com/core/v1/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<!--
This is the test suite's entry point file as it points to the test cases which in turn point to other scriptlets and resources. In general there is
no requirement on the structure of a test suite but it is a good practice to keep things organised with a consistent structure that makes sense to you
(e.g. a "test_cases" folder for the test cases, a "scriptlets" folder for scriptlets, "resources" for files to import etc.).
-->
<metadata>
<gitb:name>LDES MUST be valid against the provided SHACL shape</gitb:name>
<gitb:version>1.0</gitb:version>
<gitb:description>Test suite to validate the LDES against a certain SHACL shape</gitb:description>
</metadata>
<actors>
<!--
The IDs of the actors need to match the ones you see on the UI. Note that when you deploy a test suite it will automatically create actors based on
the below definitions if missing.
-->
<gitb:actor id="LDESServer">
<gitb:name>LDES Server</gitb:name>
<gitb:desc>The system acting as an LDES server that contains an event stream full of members</gitb:desc>
</gitb:actor>
<gitb:actor id="SHACLValidator">
<gitb:name>Shacl Validator</gitb:name>
<gitb:desc>The independent shacl validator service that will validate an LDES againt a SHACL shape
</gitb:desc>
</gitb:actor>
</actors>
<!--
The test case IDs refer to the IDs of the relevant test cases (see their root element). You can place test cases anywhere you want in the test suite archive
and they will be picked up automatically when parsing the test suite.
-->
<testcase id="ts1_tc1"/>
</testsuite>
Most important to notice here, is that de test case declared in the test_cases
folder, must be referred from this file
by adding the test case
tag with as attribute the id that has been assigned to the test case in its file.
- Compress the
validate_ldes_to_shacl_shape
folder to a zip and upload it to TestBed
If everything is set up, the folder containing everything must be zipped. After that, it can be uploaded to TestBed. This can be done either by the UI, or via the REST API. If you choose to do it via the REST API, the
curl -F updateSpecification=true -F specification=<SPECIFICATION_API_KEY> -F testSuite=@test_shacl_validator.zip --header "ITB_API_KEY: <DOMAIN_API_KEY>" -X POST http://localhost:9000/api/rest/testsuite/deploy;
- Run the test via the TestBed UI
- Build using
mvn clean package
. - Once built you can run the application using
mvn spring-boot:run
.
This project uses Spring Boot's live reloading capabilities. When running the application from your IDE or through Maven, any change in classpath resources is automatically detected to restart the application.
Running this application as a Docker container is very simple as described in Spring Boot's Docker documentation. The first step is to Install Docker and ensure it is up and running. You can now build the Docker image through Maven:
- Build the JAR file with
mvn package
. - Build the Docker image with
docker build -f ./.github/Dockerfile .
.