v3 overhaul

docs/get-started/actions/checkLink.md

@@ -11,18 +11,19 @@ description: Check if a URL returns an acceptable status code from a GET request
 
 The `checkLink` action checks if a URL returns an acceptable status code from a GET request. This action is useful for verifying that a hyperlink or image URL is valid.
 
-You can also specify
+You can specify the target URL directly as a string, or use an object for more options:
 
-- an `origin` to navigate to a URL relative to a specific path.
-- `statusCodes` to set acceptable HTTP status codes.
+- `url`: (Required in object format) The URL to check. Can be a full URL or a path. If a path is provided, an `origin` must be specified either in the step or in the configuration file.
+- `origin`: (Optional) Protocol and domain prepended to `url` when `url` is a path. If omitted and `url` is a path, the global `origin` from the configuration file is used.
+- `statusCodes`: (Optional) A single integer or an array of integers representing acceptable HTTP status codes. If omitted, defaults to `[200, 301, 302, 307, 308]`.
 
 > For comprehensive options, see the [`checkLink`](/docs/references/schemas/checkLink) reference.
 
 ## Examples
 
 Here are a few ways you might use the `checkLink` action:
 
-### Check if a link is valid
+### Check if a link is valid (string shorthand)
 
 ```json
 {
@@ -31,8 +32,46 @@ Here are a few ways you might use the `checkLink` action:
       "steps": [
         {
           "description": "Check if Google is up.",
-          "action": "checkLink",
-          "url": "https://www.google.com"
+          "checkLink": "https://www.google.com"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Check if a link is valid (object format)
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Check if Google is up.",
+          "checkLink": {
+            "url": "https://www.google.com"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Check for a specific status code response
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Check if Google is up, expecting only 200.",
+          "checkLink": {
+            "url": "https://www.google.com",
+            "statusCodes": 200
+          }
         }
       ]
     }
@@ -49,9 +88,10 @@ Here are a few ways you might use the `checkLink` action:
       "steps": [
         {
           "description": "Check if Google is up with extra status codes.",
-          "action": "checkLink",
-          "url": "https://www.google.com",
-          "statusCodes": [200, 201, 202]
+          "checkLink": {
+            "url": "https://www.google.com",
+            "statusCodes": [200, 201, 202]
+          }
         }
       ]
     }
@@ -67,10 +107,32 @@ Here are a few ways you might use the `checkLink` action:
     {
       "steps": [
         {
-          "description": "Check if Google is up with an origin.",
-          "action": "checkLink",
-          "url": "/search",
-          "origin": "https://www.google.com"
+          "description": "Check if Google search path is valid using a specific origin.",
+          "checkLink": {
+            "url": "/search",
+            "origin": "https://www.google.com"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Check a relative link using global origin
+
+Assuming a global `origin` of `https://www.google.com` is set in the configuration:
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Check if Google search path is valid using global origin.",
+          "checkLink": {
+            "url": "/search"
+          }
         }
       ]
     }
@@ -97,9 +159,10 @@ Consider the following test configuration, which checks the validity of `https:/
       "steps": [
         {
           "description": "Check site with a self-signed certificate",
-          "action": "checkLink",
-          "url": "https://self-signed.badssl.com/",
-          "statusCodes": [200, 201, 202, 301]
+          "checkLink": {
+            "url": "https://self-signed.badssl.com/",
+            "statusCodes": [200, 201, 202, 301]
+          }
         }
       ]
     }
@@ -134,22 +197,22 @@ To fix this issue, follow these steps:
    NODE_TLS_REJECT_UNAUTHORIZED=0
    ```
 
-2. Modify your test configuration to include a `setVariables` action:
+2. Modify your test configuration to include a `loadVariables` step (Note: `setVariables` is deprecated, use `loadVariables`):
 
    ```json title="bad-certificate.json" {5-8}
    {
      "tests": [
        {
          "steps": [
            {
-             "action": "setVariables",
-             "path": "ignore-certificate-problems.env"
+             "loadVariables": "ignore-certificate-problems.env"
            },
            {
              "description": "Check self-signed.badssl.com",
-             "action": "checkLink",
-             "url": "https://self-signed.badssl.com/",
-             "statusCodes": [200, 201, 202, 301]
+             "checkLink": {
+               "url": "https://self-signed.badssl.com/",
+               "statusCodes": [200, 201, 202, 301]
+             }
            }
          ]
        }

docs/get-started/actions/click.md

@@ -0,0 +1,135 @@
+---
+title: click
+layout: default
+nav_order: 2
+parent: Actions
+grand_parent: Tests
+description: Click or tap an element on the page.
+---
+
+# click
+
+The `click` action allows you to click or tap an element on the page. You can specify which mouse button to use and target elements using text or selectors.
+
+The `click` action works in several ways:
+
+- **String Shorthand:** The display text or selector of the element to find and click.
+- **Object Format:** Use an object with detailed properties for more control over the click action.
+
+If you need to find an element before clicking it, consider using the [`find`](/docs/get-started/actions/find) action, which lets you locate elements and optionally click them in a single step.
+
+**Note:** If you use the `click` action without specifying a target (using element text or selector), it will click the active element or the element at the current cursor position.
+
+## Properties
+
+When using the object format, you can specify:
+
+- `button`: (Optional) Kind of click to perform. Can be `"left"`, `"right"`, or `"middle"`. Default is `"left"`.
+- `selector`: (Optional) CSS or XPath selector of the element to click. If combined with `elementText`, the element must match both the text and the selector.
+- `elementText`: (Optional) Display text of the element to click. If combined with `selector`, the element must match both the text and the selector.
+
+> For comprehensive options, see the full [`click`](/docs/references/schemas/click) reference.
+
+## Examples
+
+Here are a few ways you might use the `click` action:
+
+### Click by element text (string shorthand)
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Click on an element with text 'Submit'",
+          "click": "Submit"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Click by selector (string shorthand)
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Click on an element matching the CSS selector",
+          "click": "#submit-button"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Click an element by text (object format)
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Left-click on a button with specific text",
+          "click": {
+            "elementText": "Submit",
+            "button": "left"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Click an element by selector (object format)
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Middle-click on an element with a specific selector",
+          "click": {
+            "selector": "#open-in-new-tab",
+            "button": "middle"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Click an element by both selector and text
+
+```json
+{
+  "tests": [
+    {
+      "steps": [
+        {
+          "description": "Click on a specific element matching both selector and text",
+          "click": {
+            "selector": ".btn",
+            "elementText": "Download",
+            "button": "left"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Related Actions
+
+- [`find`](/docs/get-started/actions/find): Find an element and optionally interact with it
+- [`type`](/docs/get-started/actions/type): Type text or special keys