docs: add an example for loading custom JSON payloads with templating

examples/using-json-payload-templates/README.md

@@ -0,0 +1,10 @@
+# Using JSON payloads with optional templating
+
+This examples shows a solution for testing an HTTP API using JSON payloads which are loaded from external JSON files, with optional templating of values inside those JSON files.
+
+It works as follows:
+
+- A custom helper function is used to load the JSON payload from a file and template it. Different request can load and template different JSON payloads.
+- Built in `fake-data` plugin and CSV payloads to provide template variables
+
+The test uses https://practicesoftwaretesting.com by https://www.testsmith.io.

examples/using-json-payload-templates/credentials.csv

@@ -0,0 +1,2 @@
+test1@example.net,very-secure-password
+test2@example.net,another-very-secure-password

examples/using-json-payload-templates/helpers.mjs

@@ -0,0 +1,24 @@
+
+import * as path from 'path';
+import Handlebars from 'handlebars';
+import * as fs from 'fs';
+
+export const loadCustomJsonPayload = async function(req, vuContext, _events) {
+  if (!req.jsonFromFile) {
+    return;
+  }
+
+  const relativePath = req.jsonFromFile.path;
+  const fullPath = path.join(vuContext.vars.$dirname, relativePath);
+  const contents = fs.readFileSync(fullPath, 'utf8');
+
+  if (!req.jsonFromFile.withVariables) {
+    const json = JSON.parse(contents);
+    req.json = json;
+  } else {
+    const template = Handlebars.compile(contents);
+    const result = template(req.jsonFromFile.withVariables);
+    const json = JSON.parse(result);
+    req.json = json;
+  }
+}

examples/using-json-payload-templates/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "using-json-payload-templates",
+  "version": "1.0.0",
+  "description": "This examples shows a solution for testing an HTTP API using JSON payloads which are loaded from external JSON files, with optional templating of values inside those JSON files.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "handlebars": "^4.7.8"
+  }
+}

examples/using-json-payload-templates/payload1.json

@@ -0,0 +1,13 @@
+{
+  "first_name": "{{ first_name }}",
+  "last_name": "{{ last_name }}",
+  "address": "{{ address }}",
+  "city": "{{ city }}",
+  "state": "{{ state }}",
+  "country": "{{ country }}",
+  "postcode": "{{ postcode }}",
+  "phone": "{{ phone }}",
+  "dob": "{{ dob }}",
+  "email": "{{ email }}",
+  "password": "{{ password }}"
+}

examples/using-json-payload-templates/test.yml

@@ -0,0 +1,63 @@
+config:
+  target: "https://api-with-bugs.practicesoftwaretesting.com"
+
+  plugins:
+    # built-in plugin to generate data with Falso
+    # https://www.artillery.io/docs/reference/extensions/fake-data
+    fake-data: {}
+    expect: {}
+
+  # This makes loadCustomJsonPayload() function available which we're using in the scenario
+  processor: './helpers.mjs'
+
+  # Load email and password fields from a CSV file
+  payload:
+    - path: "./credentials.csv"
+      fields:
+        - email
+        - password
+
+scenarios:
+  - name: Register and login
+    # This will run before every request and load and template a JSON payload if set with jsonFromFile property
+    beforeRequest: loadCustomJsonPayload
+    flow:
+      - post:
+          url: "/users/register"
+          jsonFromFile:
+            path: "./payload1.json"
+            withVariables:
+              first_name: "{{ $randFirstName() }}"
+              # last_name: "{{ $randLastName() }}"
+              last_name: "Doe" # Falso often produces values with non ASCII characters such as "é" which the application seems to reject
+              address: "{{ $randStreetAddress() }}"
+              city: "{{ $randCity() }}"
+              state: "{{ $randState() }}"
+              country:  "{{ $randCountry() }}"
+              postcode: "{{ $randZipCode() }}"
+              phone: "{{ $randPhoneNumber() }}"
+              dob: "1990-01-01"
+              email: "{{ email }}"
+              password: "{{ password }}"
+          capture:
+            - json: $.id
+              as: newUserId
+          expect:
+            statusCode: 201
+
+      - log: "User registered, user id: ${{ newUserId }}"
+
+      - post:
+          url: "/users/login"
+          json:
+            email: "{{ email }}"
+            password: "{{ password }}"
+          capture:
+            - json: $.access_token
+              as: accessToken
+          expect:
+            statusCode: 200
+
+      - log: "user logged in, access token: {{ accessToken }}"
+
+