doc-detective-common 1.0.3 → 1.2.1

package/README.md

@@ -1,38 +1,81 @@
 # Doc Detective Common
 
 ![Current version](https://img.shields.io/github/package-json/v/doc-detective/doc-detective-common?color=orange)
-[![NPM Shield](https://img.shields.io/npm/v/doc-detective-common)](https://www.npmjs.com/package/doc-detective)
+[![NPM Shield](https://img.shields.io/npm/v/doc-detective-common)](https://www.npmjs.com/package/doc-detective-common)
 [![Discord Shield](https://img.shields.io/badge/chat-on%20discord-purple)](https://discord.gg/mSCCRAhH)
 
 Shared resources for Doc Detective projects.
 
 ## Install
 
-```
+```bash
 npm i doc-detective-common
 ```
 
 ## Init
 
-```
+```javascript
 const common = require("doc-detective-common");
 ```
 
+## Methods
+
+### `.validate(schemaKey: string, object: object)`
+
+Validate that `object` matches the specified [schema](#.schemas) definition.
+
+Returns an object with the following schema:
+
+```json
+{
+  "valid": boolean,
+  "errors": [
+    {
+      "instancePath": string,
+      "schemaPath": string,
+      "keyword": string,
+      "params": [{Object}],
+      "message": string
+    }
+  ]
+}
+```
+
+#### Usage
+
+```js
+const schemaKey = "runShell_v1";
+const object = {
+  action: "runShell",
+  command: "echo $username",
+};
+console.log(common.validate(schemaKey, object));
+```
+
 ## Objects
 
-### `common.schema`
+### `.schemas`
 
 JSON schema definitions for various objects used throughout Doc Detective.
 
-Schema files are located in the [`/schema`](https://github.com/doc-detective/doc-detective-common/tree/schema/schema) directory and made available through the `common.schema` object.
+Schema objects are located in the [`/schemas`](https://github.com/doc-detective/doc-detective-common/tree/schema/schemas) directory and made available through the `.schemas` object.
 
 ```json
 {
-  "v1": {
-    "actions": {
-      "runShell": {Object}
-    },
-    "analytics": {Object}
-  }
+  "analytics_v1": {Object},
+  "checkLink_v1": {Object},
+  "click_v1": {Object},
+  "find_v1": {Object},
+  "goTo_v1": {Object},
+  "httpRequest_v1": {Object},
+  "matchText_v1": {Object},
+  "moveMouse_v1": {Object},
+  "runShell_v1": {Object},
+  "screenshot_v1": {Object},
+  "scroll_v1": {Object},
+  "startRecording_v1": {Object},
+  "stopRecording_v1": {Object},
+  "type_v1": {Object},
+  "wait_v1": {Object}
 }
 ```

package/index.js

@@ -1,13 +1,5 @@
-const v1_analytics = require("./schema/v1/analytics.schema.json");
-const v1_runShell = require("./schema/v1/actions/runShell.schema.json");
+const { schemas } = require("./src/schema");
+const { validate } = require("./src/validate");
 
-const schema = {
-  v1: {
-    actions: {
-      runShell: v1_runShell,
-    },
-    analytics: v1_analytics,
-  },
-};
-
-exports.schema = schema;
+exports.schemas = schemas;
+exports.validate = validate;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "doc-detective-common",
-  "version": "1.0.3",
+  "version": "1.2.1",
   "description": "Shared components for Doc Detective projects.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 0"
+    "test": "jest"
   },
   "repository": {
     "type": "git",
@@ -15,5 +15,16 @@
   "bugs": {
     "url": "https://github.com/doc-detective/doc-detective-common/issues"
   },
-  "homepage": "https://github.com/doc-detective/doc-detective-common#readme"
+  "homepage": "https://github.com/doc-detective/doc-detective-common#readme",
+  "devDependencies": {
+    "jest": "^29.4.1"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-errors": "^3.0.0",
+    "ajv-formats": "^2.1.1",
+    "ajv-keywords": "^5.1.0",
+    "app-root-path": "^3.1.0",
+    "uuid": "^9.0.0"
+  }
 }

package/src/schema.js

@@ -0,0 +1,47 @@
+const approot = require("app-root-path");
+const fs = require("fs");
+
+//// Init
+const schemas = {};
+
+//// Process
+loadSchemas();
+// console.log(schemas.find_v1)
+//// Export
+exports.schemas = schemas;
+
+//// Functions
+
+// Load schemas from file
+function loadSchemas() {
+  // Read files from schema directory
+  path = `${__dirname}/schemas`;
+  var files = fs.readdirSync(path);
+  // Loop through all schema files
+  files.forEach(async (file) => {
+    // Exit early for files that don't match naming pattern
+    if (!file.includes(".schema.json")) return;
+    const key = file.replace(".schema.json", "");
+    // Load schema from file
+    let schema = require(`./schemas/${file}`);
+    // Add dynamic ID based on file path
+    schema.$id = `file://${__dirname}/schemas/${file}`;
+    // Recursively update relative references with app root path
+    schema = updateRefPaths(schema);
+    // Load into `schema` object
+    schemas[key] = schema;
+  });
+}
+
+// Prepend app-root path to referenced relative paths
+function updateRefPaths(schema) {
+  for (let [key, value] of Object.entries(schema)) {
+    if (typeof value === "object") {
+      updateRefPaths(value);
+    }
+    if (key === "$ref") {
+      schema[key] = `file://${__dirname}/schemas/${value}`;
+    }
+  }
+  return schema;
+}

package/{schema/v1/analytics.schema.json → src/schemas/analytics_v1.schema.json}

@@ -441,5 +441,145 @@
   "required": [
     "version",
     "detailLevel"
+  ],
+  "examples": [
+    {
+      "version": "0.1.8",
+      "userId": "",
+      "detailLevel": "action-detailed",
+      "tests": {
+        "numberTests": 0,
+        "passed": 0,
+        "failed": 0
+      },
+      "actions": {
+        "numberActions": 0,
+        "averageNumberActionsPerTest": 0,
+        "maxActionsPerTest": 0,
+        "minActionsPerTest": 0,
+        "passed": 0,
+        "failed": 0
+      },
+      "actionDetails": {
+        "goTo": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "uri": 0
+        },
+        "find": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "wait": {
+            "numberInstances": 0,
+            "duration": 0
+          },
+          "matchText": {
+            "numberInstances": 0,
+            "text": 0
+          },
+          "moveMouse": {
+            "numberInstances": 0,
+            "alignH": 0,
+            "alignV": 0,
+            "offsetX": 0,
+            "offsetY": 0
+          },
+          "click": {
+            "numberInstances": 0
+          },
+          "type": {
+            "numberInstances": 0,
+            "keys": 0,
+            "trailingSpecialKey": 0,
+            "env": 0
+          }
+        },
+        "matchText": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "css": 0,
+          "text": 0
+        },
+        "click": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "css": 0
+        },
+        "type": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "css": 0,
+          "keys": 0,
+          "trailingSpecialKey": 0,
+          "env": 0
+        },
+        "moveMouse": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "css": 0,
+          "alignH": 0,
+          "alignV": 0,
+          "offsetX": 0,
+          "offsetY": 0
+        },
+        "scroll": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "x": 0,
+          "y": 0
+        },
+        "wait": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "duration": 0,
+          "css": 0
+        },
+        "screenshot": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "mediaDirectory": 0,
+          "filename": 0,
+          "matchPrevious": 0,
+          "matchThreshold": 0
+        },
+        "startRecording": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "mediaDirectory": 0,
+          "filename": 0,
+          "gifFps": 0,
+          "gifWidth": 0
+        },
+        "stopRecording": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0
+        },
+        "checkLink": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "uri": 0,
+          "statusCodes": 0
+        },
+        "runShell": {
+          "numberInstances": 0,
+          "passed": 0,
+          "failed": 0,
+          "command": 0,
+          "env": 0
+        }
+      }
+    }
   ]
 }

package/src/schemas/checkLink_v1.schema.json

@@ -0,0 +1,42 @@
+{
+  "title": "checkLink",
+  "type": "object",
+  "description": "Check if a URI returns an acceptable status code from a GET request.",
+  "properties": {
+    "action": {
+      "type": "string",
+      "const": "checkLink"
+    },
+    "uri": {
+      "type": "string",
+      "description": "URI to check."
+    },
+    "statusCodes": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      },
+      "default": [
+        200
+      ]
+    }
+  },
+  "required": [
+    "action",
+    "uri"
+  ],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "action": "checkLink",
+      "uri": "https://www.google.com"
+    },
+    {
+      "action": "checkLink",
+      "uri": "https://www.google.com",
+      "statusCodes": [
+        200
+      ]
+    }
+  ]
+}

package/src/schemas/checkLink_v2.schema.json

@@ -0,0 +1,54 @@
+{
+  "title": "checkLink",
+  "type": "object",
+  "description": "Check if a URL returns an acceptable status code from a GET request.",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "ID of the step."
+    },
+    "description": {
+      "type": "string",
+      "description": "Description of the step."
+    },
+    "action": {
+      "type": "string",
+      "const": "checkLink",
+      "description": "Action to perform."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL to check.",
+      "pattern": "^(http://|https://).*",
+      "transform": ["trim"]
+    },
+    "statusCodes": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "integer"
+          }
+        ]
+      },
+      "default": [200]
+    }
+  },
+  "dynamicDefaults": {
+    "id": "uuid"
+  },
+  "required": ["action", "url"],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "action": "checkLink",
+      "url": "https://www.google.com"
+    },
+    {
+      "action": "checkLink",
+      "url": "https://www.google.com",
+      "statusCodes": [200]
+    }
+  ]
+}

package/src/schemas/click_v1.schema.json

@@ -0,0 +1,60 @@
+{
+  "title": "click",
+  "type": "object",
+  "description": "Click an element specified by a CSS sepector.",
+  "properties": {
+    "action": {
+      "type": "string",
+      "const": "click"
+    },
+    "css": {
+      "type": "string",
+      "description": "CSS selector that uniquely identified the element."
+    },
+    "alignH": {
+      "type": "string",
+      "description": "Horizantal alignment of the mouse to the element.",
+      "enum": [
+        "left",
+        "center",
+        "right"
+      ]
+    },
+    "alignV": {
+      "type": "string",
+      "description": "Vertical alignment of the mouse to the element.",
+      "enum": [
+        "left",
+        "center",
+        "right"
+      ]
+    },
+    "offsetX": {
+      "type": "integer",
+      "description": "Number of pixels to offset the mouse along the X axis, relative to the element center. Positive values offset to the right. Negative values offset to the left."
+    },
+    "offsetY": {
+      "type": "integer",
+      "description": "Number of pixels to offset the mouse along the Y axis, relative to the element center. Positive values offset to the top. Negative values offset to the bottom."
+    }
+  },
+  "required": [
+    "action",
+    "css"
+  ],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "action": "click",
+      "css": "#gbqfbb"
+    },
+    {
+      "action": "click",
+      "css": "#gbqfbb",
+      "alignH": "center",
+      "alignV": "center",
+      "offsetX": 10,
+      "offsetY": 10
+    }
+  ]
+}

package/src/schemas/find_v1.schema.json

@@ -0,0 +1,137 @@
+{
+  "title": "find",
+  "type": "object",
+  "description": "Check if an element exists with the specified CSS selector.",
+  "properties": {
+    "action": {
+      "type": "string",
+      "const": "find"
+    },
+    "css": {
+      "type": "string",
+      "description": "CSS selector that uniquely identified the element."
+    },
+    "wait": {
+      "type": "object",
+      "description": "Pause before performing the next action.",
+      "additionalProperties": false,
+      "properties": {
+        "duration": {
+          "$ref": "wait_v1.schema.json#/properties/duration"
+        }
+      }
+    },
+    "matchText": {
+      "type": "object",
+      "description": "Check if an element displays the expected text.",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "$ref": "matchText_v1.schema.json#/properties/text"
+        }
+      },
+      "required": [
+        "text"
+      ]
+    },
+    "moveMouse": {
+      "type": "object",
+      "description": "Move the mouse to an element specified by a CSS sepector. Only runs if a test is being recorded.",
+      "additionalProperties": false,
+      "properties": {
+        "alignH": {
+          "$ref": "moveMouse_v1.schema.json#/properties/alignH"
+        },
+        "alignV": {
+          "$ref": "moveMouse_v1.schema.json#/properties/alignV"
+        },
+        "offsetX": {
+          "$ref": "moveMouse_v1.schema.json#/properties/offsetX"
+        },
+        "offsetY": {
+          "$ref": "moveMouse_v1.schema.json#/properties/offsetY"
+        }
+      }
+    },
+    "click": {
+      "type": "object",
+      "description": "Click an element specified by a CSS sepector.",
+      "additionalProperties": false,
+      "properties": {
+        "alignH": {
+          "$ref": "click_v1.schema.json#/properties/alignH"
+        },
+        "alignV": {
+          "$ref": "click_v1.schema.json#/properties/alignV"
+        },
+        "offsetX": {
+          "$ref": "click_v1.schema.json#/properties/offsetX"
+        },
+        "offsetY": {
+          "$ref": "click_v1.schema.json#/properties/offsetY"
+        }
+      }
+    },
+    "type": {
+      "type": "object",
+      "description": "Click an element specified by a CSS sepector.",
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "keys"
+          ]
+        },
+        {
+          "required": [
+            "trailingSpecialKey"
+          ]
+        }
+      ],
+      "properties": {
+        "keys": {
+          "$ref": "type_v1.schema.json#/properties/keys"
+        },
+        "trailingSpecialKey": {
+          "$ref": "type_v1.schema.json#/properties/trailingSpecialKey"
+        },
+        "env": {
+          "$ref": "type_v1.schema.json#/properties/env"
+        }
+      }
+    }
+  },
+  "required": [
+    "action",
+    "css"
+  ],
+  "additionalProperties": false,
+  "examples": [
+    {
+      "action": "find",
+      "css": "[title=Search]"
+    },
+    {
+      "action": "find",
+      "css": "[title=Search]",
+      "wait": {
+        "duration": 10000
+      },
+      "matchText": {
+        "text": "Search"
+      },
+      "moveMouse": {
+        "alignH": "center",
+        "alignV": "center",
+        "offsetX": 0,
+        "offsetY": 0
+      },
+      "click": {},
+      "type": {
+        "keys": "$SHORTHAIR_CAT_SEARCH",
+        "trailingSpecialKey": "Enter",
+        "env": "./sample/variables.env"
+      }
+    }
+  ]
+}