api-tuner 0.5.3 → 0.5.5

package/README.md

@@ -2,6 +2,18 @@
 
 **API** **T**ests **U**sing **n3** **R**ules
 
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Example](#example)
+- [Documentation](#documentation)
+  - [Namespaces](#namespaces)
+  - [Defining a Test Case](#defining-a-test-case)
+  - [HTTP Requests](#http-requests)
+  - [Assertions](#assertions)
+  - [Utility Rules](#utility-rules)
+- [Debugging](#debugging)
+
 ## Prerequisites
 
 - [SWI Prolog](https://www.swi-prolog.org/Download.html)
@@ -77,4 +89,200 @@ api-tuner test.n3
 
 ## More examples
 
-TBD
+See the [Documentation](#documentation) section below for more examples and detailed documentation of the N3 rules.
+
+## Documentation
+
+This section describes the N3 rules and vocabulary used by `api-tuner` for defining and executing API tests.
+
+### Namespaces
+
+Commonly used prefixes in `api-tuner` tests:
+
+```turtle
+PREFIX tuner: <https://api-tuner.described.at/>
+PREFIX resource: <https://api-tuner.described.at/resource#>
+PREFIX earl: <http://www.w3.org/ns/earl#>
+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#>
+```
+
+### Defining a Test Case
+
+A test case is defined as an `earl:TestCase`. The core logic of the test resides in `tuner:formula`.
+
+```turtle
+<#myTest>
+  a earl:TestCase ;
+  rdfs:label "Description of my test" ;
+  tuner:formula {
+    # Test logic goes here
+  } .
+```
+
+If the formula evaluates to true (all statements inside match), the test is considered `earl:passed`.
+
+### HTTP Requests
+
+#### Request Object
+
+You can define a detailed request using the `tuner:Request` class.
+
+```turtle
+<#test> tuner:request [
+  a tuner:Request ;
+  tuner:method "POST" ;
+  tuner:url <http://example.com/api> ;
+  tuner:header ( "Accept" "application/json" ) ;
+  tuner:query ( "verbose" "true" ) ;
+  tuner:body { <#s> <#p> <#o> }
+] .
+```
+
+To execute the request and get a response:
+```turtle
+<#test> tuner:request ?req .
+?req tuner:response ?res .
+```
+
+#### Simplified Helpers
+
+The `resource:` namespace provides shortcuts for common HTTP methods. These helpers automatically assert a `200 OK` response status unless used in a way that captures the response for further assertions.
+
+- `( <url> ?res ) resource:getIn []`
+- `( <url> ?body ?res ) resource:postIn []`
+- `( <url> ?res ) resource:postIn []` (no body)
+- `( <url> ?body ?res ) resource:putIn []`
+
+Example:
+```turtle
+( <http://example.com> ?res ) resource:getIn [] .
+```
+
+#### Request Bodies
+
+`api-tuner` supports different types of request bodies:
+
+1.  **Inline RDF**: Uses an N3 formula. It is serialized as Turtle and sent with `Content-Type: text/turtle`.
+    ```turtle
+    tuner:body { <#s> <#p> <#o> }
+    ```
+2.  **File Reference**: Sends the contents of a local file.
+    ```turtle
+    tuner:body <file:data.json>
+    ```
+3.  **Multipart Form**:
+    ```turtle
+    tuner:body [
+      tuner:form ( "field1" "value1" ) ;
+      tuner:form ( "fileField" <file:photo.jpg> "image/jpeg" ) ;
+    ]
+    ```
+
+#### Query Parameters
+
+Query parameters can be added to a request using `tuner:query`.
+
+```turtle
+?req tuner:query ( "name" "value" ) .
+```
+
+### Assertions
+
+Assertions are performed on the `tuner:Response` object (usually captured in a variable like `?res`).
+
+#### Status Code
+
+Assert the HTTP status code:
+```turtle
+?res tuner:http_code 200 .
+```
+
+#### Headers
+
+Assert the presence and value of an HTTP header. Header names are case-insensitive.
+
+- **Exact match**:
+  ```turtle
+  ?res tuner:header ( "Content-Type" "application/json" ) .
+  ```
+- **Regex match**:
+  ```turtle
+  ?res tuner:header ( "Content-Type" "application/.*" string:matches ) .
+  ```
+
+#### Body
+
+- **Raw body string**:
+  ```turtle
+  ?res tuner:body ?body .
+  ?body string:contains "Expected Text" .
+  ```
+- **RDF Semantics**: If the response is RDF, you can use `log:includes` to check its content.
+  ```turtle
+  ?res tuner:body ?body.
+  ?body log:includes { <#s> <#p> <#o> } .
+  ```
+  ⚠️ Be careful when using `?res!log:includes` resource path shorthand which will not work inside `tuner:formula`. Please refer to [this discussion](https://github.com/eyereasoner/eye/issues/148#issuecomment-2810940959).
+
+<<<<<<< json-assertions
+- **JSON Path**: If the response is JSON, you can use `tuner:jsonPath` to assert values within the body.
+  ```turtle
+  ?res tuner:body ?body .
+  # Exact match
+  ?body tuner:jsonPath ( "$.foo" "bar" ) .
+  # Custom assertion (e.g. regex, contains, math)
+  ?body tuner:jsonPath ( "$.baz" "42" string:contains ) .
+  ```
+
+=======
+>>>>>>> master
+#### Generic Assertions
+
+Use `tuner:assertThat` to fail a test with a custom message if a condition is not met.
+
+```turtle
+{ ?value math:greaterThan 10 }!tuner:assertThat "Value should be greater than 10" .
+```
+
+### Utility Rules
+
+#### Logging
+
+Print messages to the console during test execution (depending on log level).
+
+- `?message^tuner:info`: Prints an INFO message.
+- `?message^tuner:trace`: Prints a DEBUG message.
+
+Example:
+```turtle
+"Starting request"^tuner:info .
+```
+
+#### File Operations
+
+- `() file:temp ?path`: Generates a temporary file path.
+- `?path file:rm ?any`: Deletes a file.
+- `?relative file:libPath ?absolute`: Resolves a path relative to the `api-tuner` library.
+
+### Debugging
+
+Setting the `--debug` flag will print verbose response information. The `--raw` flag will print
+the raw triples produced by the n3 rules.
+
+Additionally, you can inspect the raw response files, which are written to the system's temp directory. The are prefixed
+with `api-tuner`. Thus, you can list them with `ls -l "${TMPDIR:-/tmp}"/api-tuner*`, or upload to CI artifacts, as shown
+in the GitHub Workflow step example below.
+
+```yaml
+- run: npx api-tuner ...
+  env:
+    TMPDIR: ${{ runner.temp }}
+- if: failure()
+  name: upload api-tuner response data
+  uses: actions/upload-artifact@v7
+  with:
+    name: api-tuner-debug
+    path: '${{ runner.temp }}/api-tuner*'
+```

package/bin/jsonpath.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)
+
+# find JS entrypoint
+executable="$SCRIPT_DIR/../lib/jsonpath.js"
+
+# if tsx exists in path
+if command -v tsx > /dev/null 2>&1
+then
+  # use tsx
+  node --import tsx --no-warnings "$executable" "$@"
+else
+  # use plain node
+  node "$executable" "$@"
+fi

package/lib/jsonpath.js

@@ -0,0 +1,23 @@
+/* eslint-disable no-console */
+import { JSONPath } from 'jsonpath-plus';
+import getStream from 'get-stream';
+async function main() {
+    const path = process.argv[2];
+    if (!path) {
+        console.error('Usage: node jsonpath.js <path>');
+        process.exit(1);
+    }
+    const jsonString = await getStream(process.stdin);
+    try {
+        const json = JSON.parse(jsonString);
+        const result = JSONPath({ path, json, wrap: false });
+        if (result !== undefined && result !== null) {
+            process.stdout.write(JSON.stringify(result));
+        }
+    }
+    catch (e) {
+        console.error('Error parsing JSON or executing JSONPath:', e.message);
+        process.exit(1);
+    }
+}
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-tuner",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "main": "index.js",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,6 @@
     "rules"
   ],
   "dependencies": {
-    "@changesets/cli": "^2.29.7",
     "@jeswr/pretty-turtle": "^1.8.2",
     "@sindresorhus/merge-streams": "^4.0.0",
     "@zazuko/env-node": "^3",
@@ -36,11 +35,13 @@
     "get-stream": "^9.0.1",
     "is-absolute-url": "^4.0.1",
     "jsonld": "^9",
+    "jsonpath-plus": "^10.2.0",
     "rdf-validate-shacl": "^0.6.5",
     "replacestream": "^4.0.3",
     "tar": "^7.5.7"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "@rdfjs/types": "^2",
     "@tpluscode/eslint-config": "^0.5.0",
     "@types/jsonld": "^1.5.15",
@@ -53,7 +54,7 @@
     "eslint": "^8.57.1",
     "eslint-import-resolver-typescript": "^4.3.4",
     "husky": "^9.1.7",
-    "lint-staged": "^15.4.3",
+    "lint-staged": "^16.4.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.3"
   },

package/rules/assertions.n3

@@ -73,6 +73,31 @@ prefix log: <http://www.w3.org/2000/10/swap/log#>
   ) log:ifThenElseIn [] .
 } .
 
+{
+  ?body tuner:jsonPath ( ?path ?expected ) .
+} <= {
+  ?body tuner:jsonPath ( ?path ?expected log:equalTo ) .
+} .
+
+{
+  ?body tuner:jsonPath ( ?path ?expected ?builtIn ) .
+} <= {
+  ?body log:rawType log:Literal .
+  ( "echo " ?body " | bin/jsonpath.sh '" ?path "' " )!string:concatenation log:shell ?actualRaw .
+
+  # remove surrounding quotes added by the shell
+  ( ( ?actualRaw '^\"' "")!string:replace '\"$' "") string:replace ?actual .
+
+  (
+    { ?actual ?builtIn ?expected }
+    true
+    {
+      ("Expected JSON path '" ?path "' to satisfy '" ?builtIn " " ?expected "' but got '" ?actual "'")!string:concatenation^tuner:info .
+      true log:equalTo false .
+    }
+  ) log:ifThenElseIn ?SCOPE .
+} .
+
 {
   ?res tuner:header ( ?name ?value ) .
 } <= {

package/rules/curl-body.n3

@@ -30,6 +30,14 @@ prefix math: <http://www.w3.org/2000/10/swap/math#>
   ( " --data-binary " ?fileUrl!file:curlFileReference ) string:concatenation ?curlArgs .
 } .
 
+{
+  ?literalBody </#body> ( ?curlArgs [] ) .
+} <= {
+  ?literalBody log:rawType log:Literal .
+
+  ( " -d '" ?literalBody "'" ) string:concatenation ?curlArgs .
+} .
+
 {
   ?multipartBody </#body> ( ?curlArgs [] ) .
 } <= {

package/rules/files.n3

@@ -15,7 +15,7 @@ prefix file: <http://www.w3.org/2000/10/swap/file#>
 } <= {
   ?uri log:uri ( "urn:rand:" ( 1000 )!e:random )!string:concatenation .
   # log:shell captures the traling newline
-  ( "mktemp -d"!log:shell "\n" "" ) string:replace ?tempDir .
+  ( "mktemp -t api-tuner -d 2>/dev/null || mktemp -d -t api-tuner.XXXXXXXX"!log:shell "\n" "" ) string:replace ?tempDir .
 
   (
     ?tempDir