api-tuner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zazuko GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# 🎛️ API Tun3r 🎛️
+
+**API** **T**ests **U**sing **n3** **R**ules
+
+## Prerequisites
+
+- [SWI Prolog](https://www.swi-prolog.org/Download.html)
+
+## Installation
+
+`npm i api-tuner`
+
+## Usage
+
+```sh
+> api-tuner --help
+Usage: api-tuner [options] <path>...
+
+Options:
+  --silent           Less output
+  --debug            Enable debug output
+  --raw              Output raw results from eye
+  --base-iri <iri>   Specify the base IRI for parsing the test case files
+  --version          Show version information
+  --help             Show this help message
+```
+
+## Example
+
+Create a test case file `test.n3`:
+
+```turtle
+# test.n3
+PREFIX : <http://example.com/>
+PREFIX earl: <http://www.w3.org/ns/earl#>
+PREFIX tuner: <https://api-tuner.described.at/>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+PREFIX log: <http://www.w3.org/2000/10/swap/log#>
+PREFIX string: <http://www.w3.org/2000/10/swap/string#>
+
+:getExampleDotCom
+  a earl:TestCase ;
+  rdfs:label "Simple GET test" ;
+.
+
+# Configure a request
+:req
+  a tuner:Request ;
+  tuner:url <http://localhost:1080/example.com> ;
+  tuner:method "GET" ;
+.
+
+{
+  # Execute the request and capture its response
+  :req tuner:response ?res .
+
+  # Check the response status code and content type
+  ?res tuner:http_code 200 ;
+    tuner:header ( "content-type" "text/html" ) ;
+  .
+
+  # Check the body contains the work "Example"
+  ?res!tuner:body string:contains "Example Domain" .
+} => {
+  # Use te EARL vocabulary to assert the test passed
+  :getExampleDotCom earl:outcome earl:passed .
+} .
+```
+
+Execute the test case:
+
+```sh
+api-tuner test.n3
+```
+
+## More examples
+
+TBD

package/bin/tuner.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+SCRIPT_PATH=$(dirname "$(readlink -f "$0")")
+
+eye="swipl -x ${SCRIPT_PATH}/../eye/lib/eye.pvm --"
+
+# function prints version
+function version() {
+  # read from ./package.json
+  API_TUNER_VERSION=$(cat "${SCRIPT_PATH}"/../package.json | grep version | head -1 | awk -F: '{ print $2 }' | sed 's/[",]//g' | tr -d '[[:space:]]')
+  echo "API-TUNER v${API_TUNER_VERSION}"
+  $eye --version
+}
+
+ function usage() {
+   echo "Usage: api-tuner [options] <path>..."
+   echo ""
+   echo "Options:"
+   echo "  --silent           Less output"
+   echo "  --debug            Enable debug output"
+   echo "  --raw              Output raw results from eye"
+   echo "  --base-iri <iri>   Specify the base IRI for parsing the test case files"
+   echo "  --version          Show version information"
+   echo "  --help             Show this help message"
+ }
+
+SILENT=false
+BASE_IRI=""
+DEBUG=false
+SUMMARY="node ${SCRIPT_PATH}/../lib/summarise-results.js --summary"
+PATHS=()
+# USAGE: ./tuner.sh --debug --version ...paths
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --debug)
+      DEBUG=true
+      shift
+      ;;
+    --silent)
+      SILENT=true
+      shift
+      ;;
+    --raw)
+      SUMMARY="node ${SCRIPT_PATH}/../lib/summarise-results.js"
+      shift
+      ;;
+    --base-iri)
+      BASE_IRI="$2"
+      shift
+      shift
+      ;;
+    --version)
+      version
+      exit 0
+      ;;
+    --help)
+      usage
+      exit 0
+      ;;
+    *)
+      PATHS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# if no paths
+if [ ${#PATHS[@]} -eq 0 ]; then
+  usage
+  exit 1
+fi
+
+ARGS="--quiet --nope --pass"
+
+if [ "$DEBUG" = true ]; then
+  ARGS="$ARGS ${SCRIPT_PATH}/../logging/debug.n3"
+fi
+
+if [ "$SILENT" != true ]; then
+  ARGS="$ARGS ${SCRIPT_PATH}/../logging/info.n3"
+fi
+
+MERGED="$(mktemp)"
+if [ -n "$BASE_IRI" ]; then
+  echo "base <$BASE_IRI>" > "$MERGED"
+fi
+
+for path in "${PATHS[@]}"; do
+  cat "$path" >> "$MERGED"
+done
+
+$eye $ARGS "${SCRIPT_PATH}"/../rules/*.n3 "${MERGED}" | $SUMMARY

package/lib/curl-format.txt

@@ -0,0 +1,4 @@
+{
+  "response": %{json},
+  "headers": %{header_json}
+}

package/lib/download-eye.sh

@@ -0,0 +1,6 @@
+curl -sL https://github.com/eyereasoner/eye/archive/refs/tags/v"${EYE_VERSION}".tar.gz -o eye.tar.gz
+
+tar -xvzf eye.tar.gz
+rm eye.tar.gz
+
+mv eye-"${EYE_VERSION}" eye

package/lib/merge-curl-output.js

@@ -0,0 +1,60 @@
+import * as fs from 'node:fs/promises'
+import { createReadStream } from 'node:fs'
+import jsonld from 'jsonld'
+import rdf from '@zazuko/env-node'
+import { write } from '@jeswr/pretty-turtle'
+
+const ns = rdf.namespace('https://api-tuner.described.at/');
+
+(async () => {
+  const bodyPath = process.argv[2]
+
+  const curlJsonPath = `${bodyPath}.curl.json`
+  const { response: responseJson, headers: headersJson } = JSON.parse((await fs.readFile(curlJsonPath)).toString())
+  /**
+   * @type {Record<string, string | number | null>}
+   */
+  const curlJsonLd = Object.assign({
+    '@context': {
+      '@vocab': ns().value,
+    },
+  }, responseJson)
+
+  /**
+   * @type {import('@rdfjs/types').Quad[]}
+   */
+  const responseQuads = await jsonld.toRDF(curlJsonLd)
+  const response = rdf.clownface({
+    dataset: rdf.dataset(responseQuads),
+  }).has(ns.exitcode).addOut(rdf.ns.rdf.type, ns.Response)
+
+  let contentType
+  if (typeof responseJson.content_type === 'string') {
+    contentType = responseJson.content_type.substring(0, responseJson.content_type.indexOf(';')) || responseJson.content_type
+  }
+  let parser
+  if (contentType) {
+    parser = rdf.formats.parsers.get(contentType)
+  }
+  if (parser) {
+    const bodyGraph = rdf.blankNode()
+    const bodyStream = parser.import(createReadStream(bodyPath))
+    for await (const quad of bodyStream) {
+      response.dataset.add(rdf.quad(quad.subject, quad.predicate, quad.object, bodyGraph))
+    }
+    response.addOut(ns.body, bodyGraph)
+  } else {
+    const body = await fs.readFile(bodyPath, 'utf-8')
+    if (body) {
+      response.addOut(ns.body, body)
+    }
+  }
+
+  const headers = Object.entries(headersJson).flatMap(([header, values]) =>
+    values.map(value => response.blankNode().addOut(ns.name, header).addOut(ns.value, value)))
+  response.addOut(ns.headers, headers)
+
+  process.stdout.write(await write([...response.dataset], {
+    format: 'text/n3',
+  }))
+})()

package/lib/replace-quotes.sh

@@ -0,0 +1 @@
+sed -e 's/\\"/"/g'

package/lib/shapes.ttl

@@ -0,0 +1,14 @@
+PREFIX earl: <http://www.w3.org/ns/earl#>
+PREFIX sh: <http://www.w3.org/ns/shacl#>
+
+[
+  a sh:NodeShape ;
+  sh:targetClass earl:TestCase ;
+  sh:property
+    [
+      sh:path earl:outcome ;
+      sh:hasValue earl:passed ;
+      sh:maxCount 1 ;
+      sh:message "Test failed" ;
+    ] ;
+] .

package/lib/summarise-results.js

@@ -0,0 +1,44 @@
+import { PassThrough } from 'node:stream'
+import SHACLValidator from 'rdf-validate-shacl'
+import rdf from '@zazuko/env-node'
+import yargs from 'yargs'
+import { hideBin } from 'yargs/helpers'
+
+const argv = yargs(hideBin(process.argv)).argv
+
+const shapesTtl = new URL('./shapes.ttl', import.meta.url)
+
+;(async () => {
+  const shapes = await rdf.dataset().import(rdf.fromFile(shapesTtl))
+  const validator = new SHACLValidator(shapes, {
+    factory: rdf,
+  })
+
+  const dataPassThrough = new PassThrough()
+  process.stdin.pipe(dataPassThrough)
+
+  if (!argv.summary) {
+    process.stdin.pipe(process.stdout)
+  }
+
+  const data = await rdf.dataset().import(rdf.formats.parsers.import('text/n3', dataPassThrough, {
+    format: 'n3',
+  }))
+
+  const validationReport = validator.validate(data)
+
+  if (argv.summary) {
+    const testCases = rdf.clownface({ dataset: data }).has(rdf.ns.rdf.type, rdf.ns.earl.TestCase)
+
+    for (const testCase of testCases.toArray()) {
+      const result = validationReport.results.find(result => result.focusNode.equals(testCase.term))
+      if (result?.severity.equals(rdf.ns.sh.Violation)) {
+        process.stdout.write(`❌  FAIL <${testCase.value}>\n`)
+      } else {
+        process.stdout.write(`✅  PASS <${testCase.value}>\n`)
+      }
+    }
+  }
+
+  process.exit(validationReport.conforms ? 0 : 1)
+})()

package/logging/debug.n3

@@ -0,0 +1,4 @@
+PREFIX e: <http://eulersharp.sourceforge.net/2003/03swap/log-rules#>
+PREFIX tuner: <https://api-tuner.described.at/>
+
+[ tuner:logLevel 'debug' ] .

package/logging/info.n3

@@ -0,0 +1,4 @@
+PREFIX e: <http://eulersharp.sourceforge.net/2003/03swap/log-rules#>
+PREFIX tuner: <https://api-tuner.described.at/>
+
+[ tuner:logLevel 'info' ] .

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "api-tuner",
+  "version": "0.1.0",
+  "main": "index.js",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "api-tuner": "./bin/tuner.sh"
+  },
+  "scripts": {
+    "download-eye": "EYE_VERSION=11.5.2 ./lib/download-eye.sh",
+    "postinstall": "([ -d eye ] || npm run download-eye) && eye/install.sh --prefix=eye",
+    "prepare": "husky",
+    "lint": "eslint . --quiet --ignore-path .gitignore",
+    "test": "./bin/tuner.sh tests/*.n3 tests/**/*.n3",
+    "release": "changeset publish"
+  },
+  "files": [
+    "bin/tuner.sh",
+    "logging",
+    "lib",
+    "rules"
+  ],
+  "dependencies": {
+    "@changesets/cli": "^2.27.12",
+    "@jeswr/pretty-turtle": "^1.5.0",
+    "@zazuko/env-node": "^2.1.4",
+    "jsonld": "^8.3.3",
+    "rdf-validate-shacl": "^0.5.6",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@rdfjs/types": "^1",
+    "@tpluscode/eslint-config": "^0.5.0",
+    "@types/jsonld": "^1.5.15",
+    "@types/rdf-validate-shacl": "^0.4.9",
+    "@types/yargs": "^17.0.33",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.4.3"
+  },
+  "lint-staged": {
+    "*.{js,ts}": [
+      "eslint --fix --quiet"
+    ]
+  }
+}

package/rules/assertions.n3

@@ -0,0 +1,58 @@
+PREFIX tuner: <https://api-tuner.described.at/>
+prefix string: <http://www.w3.org/2000/10/swap/string#>
+prefix log: <http://www.w3.org/2000/10/swap/log#>
+
+{
+  ?res tuner:http_code ?value .
+} <= {
+  ?res log:includes {
+    [] a tuner:Response ;
+    tuner:http_code ?actualValue .
+  } .
+
+  (
+    { ?actualValue log:equalTo ?value }
+    true
+    {
+      ("Expected status code " ?value " but got " ?actualValue)!string:concatenation^tuner:info .
+      true log:equalTo false .
+    }
+  ) log:ifThenElseIn ?SCOPE .
+} .
+
+{
+  ?res tuner:body ?body .
+} <= {
+  ?res log:includes {
+    [] a tuner:Response ; tuner:body ?body .
+  } .
+} .
+
+{
+  ?res tuner:header ( ?name ?value ) .
+} <= {
+  ?res tuner:header ( ?name ?value log:equalTo ) .
+}.
+
+{
+  ?res tuner:header ( ?name ?value ?builtIn ) .
+} <= {
+  ?name string:lowerCase ?nameLower .
+
+  ?res log:includes {
+    [] a tuner:Response ;
+    tuner:headers [
+      tuner:name ?nameLower ;
+      tuner:value ?actualValue ;
+    ] .
+  } .
+
+  (
+    { ?actualValue ?builtIn ?value }
+    true
+    {
+      ("Expected header '" ?name "' '" ?value "' to satisfy '" ?builtIn "' but got '" ?actualValue "'")!string:concatenation^tuner:info .
+      true log:equalTo false .
+    }
+  ) log:ifThenElseIn ?SCOPE .
+} .

package/rules/curl-body.n3

@@ -0,0 +1,58 @@
+PREFIX list: <http://www.w3.org/2000/10/swap/list#>
+PREFIX tuner: <https://api-tuner.described.at/>
+PREFIX string: <http://www.w3.org/2000/10/swap/string#>
+PREFIX log: <http://www.w3.org/2000/10/swap/log#>
+prefix file: <http://www.w3.org/2000/10/swap/file#>
+prefix e: <http://eulersharp.sourceforge.net/2003/03swap/log-rules#>
+
+{
+  ?body </#body> ( ?curlArgs ?requestBodyFile ) .
+} <= {
+  ?body log:rawType log:Formula .
+  ?body log:n3String ?serialized .
+  () file:temp ?requestBodyFile .
+
+  # Save body to file so that it can be used in the curl command reliably
+  (
+    "echo '" ?serialized "' | "
+    # need to replace quotes around string
+    ( "lib/replace-quotes.sh"!file:libPath )!string:concatenation
+    " > " ?requestBodyFile
+  )!string:concatenation!e:exec .
+
+  ( " -H 'Content-Type:text/turtle' --data-binary @" ?requestBodyFile ) string:concatenation ?curlArgs .
+} .
+
+{
+  ?fileUrl </#body> ( ?curlArgs [] ) .
+} <= {
+  ( " --data-binary " ?fileUrl!file:curlFileReference ) string:concatenation ?curlArgs .
+} .
+
+{
+  ?multipartBody </#body> ( ?curlArgs [] ) .
+} <= {
+  ?multipartBody!log:rawType list:in ( log:LabeledBlankNode log:UnlabeledBlankNode ) .
+
+  (
+    ?formField
+    {
+      ?multipartBody tuner:form ( ?name ?value ) .
+
+      (
+        { ?value log:rawType log:Literal }
+        {
+          ( " -F " ?name "=" ?value ) string:concatenation ?formField .
+        }
+        {
+          ( " -F " ?name "=" ?value!file:curlFileReference ) string:concatenation ?formField .
+        }
+      ) log:ifThenElseIn [] .
+    }
+    ?formFields
+  ) log:collectAllIn [] .
+
+  (
+    ?formFields!string:concatenation
+  ) string:concatenation ?curlArgs .
+} .

package/rules/files.n3

@@ -0,0 +1,50 @@
+prefix e: <http://eulersharp.sourceforge.net/2003/03swap/log-rules#>
+prefix string: <http://www.w3.org/2000/10/swap/string#>
+prefix log: <http://www.w3.org/2000/10/swap/log#>
+prefix file: <http://www.w3.org/2000/10/swap/file#>
+
+{
+  () file:temp ?path .
+} <= {
+  ( "" ) file:temp ?path .
+} .
+
+{
+  ( ?suffix ) file:temp ?path .
+} <= {
+  ?uri log:uri ( "urn:rand:" ( 1000 )!e:random )!string:concatenation .
+
+  (
+    #"/tmp/"
+    ?uri!log:uuid
+    ?suffix
+  ) string:concatenation ?path .
+} .
+
+{
+  ?path file:rm ?iDoNotCare .
+} <= {
+  ( "rm " ?path )!string:concatenation!e:exec .
+} .
+
+{
+  ?relative file:libPath ?absolute .
+} <= {
+  (
+    (<>!log:uri "/[^/]+$" "/")!string:replace 8
+  ) string:substring ?basePath .
+
+  (
+    ?basePath "../" ?relative
+  ) string:concatenation ?absolute .
+} .
+
+{
+  ?fileUrl file:curlFileReference ?ref .
+} <= {
+  ?fileUrl log:uri ?fileUri .
+  ?fileUri string:startsWith "file:" .
+  ( ?fileUri 6 ) string:substring ?relative .
+
+  ( "@$(pwd)/" ?relative ) string:concatenation ?ref .
+} .

package/rules/logging.n3

@@ -0,0 +1,24 @@
+PREFIX tuner: <https://api-tuner.described.at/>
+prefix earl: <http://www.w3.org/ns/earl#>
+prefix log: <http://www.w3.org/2000/10/swap/log#>
+prefix string: <http://www.w3.org/2000/10/swap/string#>
+
+{
+  ?left tuner:trace ?right .
+} <= {
+  (
+    { [] tuner:logLevel 'debug' }
+    { 'DEBUG' log:trace ?right . }
+    true
+  ) log:ifThenElseIn ?SCOPE .
+} .
+
+{
+  ?left tuner:info ?right .
+} <= {
+  (
+    { [] tuner:logLevel 'info' }
+    { 'INFO' log:trace ?right . }
+    true
+  ) log:ifThenElseIn ?SCOPE .
+} .

package/rules/requests.n3

@@ -0,0 +1,78 @@
+PREFIX list: <http://www.w3.org/2000/10/swap/list#>
+prefix e: <http://eulersharp.sourceforge.net/2003/03swap/log-rules#>
+prefix log: <http://www.w3.org/2000/10/swap/log#>
+prefix string: <http://www.w3.org/2000/10/swap/string#>
+PREFIX tuner: <https://api-tuner.described.at/>
+prefix file: <http://www.w3.org/2000/10/swap/file#>
+prefix earl: <http://www.w3.org/ns/earl#>
+
+{
+  (?fieldName ?fieldValue) tuner:headerArg ?curlArg .
+} <= {
+  ( " -H '" ?fieldName ":" ?fieldValue "'" ) string:concatenation ?curlArg .
+} .
+
+{
+  ?req tuner:response ?res .
+} <= {
+  {
+    ?req a tuner:Request .
+    ?req tuner:method ?method .
+    ?req tuner:url ?endpointUri .
+  } log:callWithOptional {
+    ?req tuner:body ?body .
+  } .
+  ({ ?req tuner:done true } false true) log:ifThenElseIn ?SCOPE .
+  true log:becomes { ?req tuner:done true } .
+
+  (
+    { ?req tuner:header [] . }
+    {
+      ( ?header { ?req tuner:header ?header } ?headers ) log:collectAllIn [] .
+      ( ?headers tuner:headerArg )!list:map string:concatenation ?headersArgs .
+    }
+    { ?headersArgs log:equalTo "" }
+  ) log:ifThenElseIn [] .
+
+  ?endpointUri log:uri ?endpoint .
+
+  ( ?method " " ?endpoint )!string:concatenation^tuner:trace .
+
+  () file:temp ?responseBodyFile .
+  ( ?responseBodyFile ".curl.json" ) string:concatenation ?responseHeadersFile .
+  ( ?responseBodyFile ".n3" ) string:concatenation ?responseFile .
+
+  ( "Calling " ?method " " ?endpoint )!string:concatenation^tuner:info .
+
+  (
+    { ?req tuner:body ?body  }
+    { ?body </#body> ( ?bodyArgs ?requestBodyFile ) }
+    { ?bodyArgs log:equalTo "" }
+  ) log:ifThenElseIn [] .
+
+  (
+    "curl -s -X " ?method " '" ?endpoint "'"
+    ?headersArgs
+    ?bodyArgs
+    " -w @" ( "lib/curl-format.txt"!file:libPath )!string:concatenation
+    " -o " ?responseBodyFile
+    " > " ?responseHeadersFile
+  ) string:concatenation ?command .
+
+  ?command^tuner:trace .
+  ?command!e:exec .
+
+  (
+    "node " "lib/merge-curl-output.js"!file:libPath " "
+    ?responseBodyFile
+    " > " ?responseFile
+  )!string:concatenation!e:exec .
+
+  ("file://" ?responseFile)!string:concatenation^log:uri log:semantics ?res .
+  ?res^tuner:trace .
+
+  ( { ?requestBodyFile log:rawType log:Literal } { ?requestBodyFile!file:rm } true ) log:ifThenElseIn [] .
+  ?responseHeadersFile!file:rm .
+  ?responseBodyFile!file:rm .
+  ?responseFile!file:rm .
+} .