Skip to main content

​
Execute Tests

The Voidr API provides two main endpoints for executing tests: one for running all tests in an application, and another for executing specific test plans with granular control.

​
Execute All Application Tests

The POST /executions/application endpoint creates executions for all test plans in an application.

​
Request

curl -sS --location "$API_URL/executions/application" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "applicationId": "YOUR_APPLICATION_ID",
    "environment": "YOUR_ENVIRONMENT",
    "provider": "PLAYWRIGHT"
  }'

​
Parameters

FieldTypeRequiredDescription
applicationIdstring✓Application ID (MongoDB ObjectId)
environmentstring✓Execution environment (e.g., production, staging)
providerstring✓Test provider: PLAYWRIGHT or CYPRESS
browserobject○Browser configuration (name, version, channel)
tagsstring[]○Tags to filter/group executions
notificationIdsstring[] or null○Webhook IDs to notify (null = all, [] = none)

​
Response

{
  "success": true,
  "data": {
    "applicationExecutionId": "APPLICATION_EXECUTION_ID",
    "total": 0,
    "created": 0,
    "skipped": 0,
    "executions": [
      {
        "_id": "EXECUTION_ID",
        "code": "EX-XXXX",
        "status": "QUEUED"
      }
    ]
  }
}

​
Response Fields

FieldDescription
applicationExecutionIdUUID that groups all executions from this trigger
totalTotal number of plans processed
createdNumber of executions created
skippedNumber of plans ignored (already running)

​
Execute Specific Test Plan

The POST /executions endpoint creates an execution for a specific test plan (standard endpoint used by the platform).

​
Request (Complete Plan)

curl -sS --location "$API_URL/executions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "applicationId": "YOUR_APPLICATION_ID",
    "planId": "YOUR_PLAN_ID",
    "environment": "YOUR_ENVIRONMENT",
    "provider": "PLAYWRIGHT"
  }'

​
Required Parameters

FieldTypeDescription
applicationIdstringApplication ID (MongoDB ObjectId)
planIdstringTest plan ID (MongoDB ObjectId)
environmentstringExecution environment (e.g., production, staging)
providerstringTest provider: PLAYWRIGHT or CYPRESS

​
Optional Parameters

FieldTypeDescription
browserobjectBrowser configuration with name, version, channel
deviceobjectDevice configuration with name
viewportobjectViewport configuration with width and height
localestringLocale (e.g., en-US)
timezonestringIANA timezone (e.g., UTC)
tagsstring[]Tags to filter/group executions
notificationIdsstring[] or nullWebhook IDs to notify (null = all, [] = none)
idempotencyKeystringIdempotency key to prevent duplicate executions
ciobjectCI/CD information with provider, runUrl, pipelineId, workflow
branchstringBranch name
commitobjectCommit information with sha, author, message, timestamp, url

​
Execution Modes

​
Mode 1: Complete Plan (Default)

Executes all test cases in the plan. 
{
  "applicationId": "...",
  "planId": "...",
  "environment": "production",
  "provider": "PLAYWRIGHT"
}

​
Mode 2: By Modules

{
  "applicationId": "...",
  "planId": "...",
  "environment": "production",
  "provider": "PLAYWRIGHT",
  "moduleSlugs": ["AUTEN", "CHECKOUT"]
}

​
Mode 3: By Suites

{
  "applicationId": "...",
  "planId": "...",
  "environment": "production",
  "provider": "PLAYWRIGHT",
  "suiteSlugs": ["login-suite", "payment-suite"]
}

​
Mode 4: By Specific Targets

{
  "applicationId": "...",
  "planId": "...",
  "environment": "production",
  "provider": "PLAYWRIGHT",
  "targets": [
    {
      "moduleSlug": "AUTEN",
      "suiteSlug": "login-suite",
      "testCaseSlug": "TC-001"
    },
    {
      "moduleSlug": "CHECKOUT",
      "suiteSlug": "payment-suite",
      "testCaseSlug": "TC-005"
    }
  ]
}
Rule: Use only one mode per request (do not combine targets, moduleSlugs, and suiteSlugs).

​
Response

{
  "success": true,
  "data": {
    "_id": "EXECUTION_ID",
    "code": "EX-XXXX",
    "applicationId": "YOUR_APPLICATION_ID",
    "planId": "YOUR_PLAN_ID",
    "environment": "YOUR_ENVIRONMENT",
    "provider": "PLAYWRIGHT",
    "status": "QUEUED",
    "createdAt": "ISO_8601_TIMESTAMP"
  }
}

​
Select Which Notifications Receive Results

When creating an execution, use notificationIds to control which enabled notifications receive results:
  • null or omitted: notifies all enabled notifications in the organization (default)
  • [] (empty array): does not notify anyone
  • ["id1", "id2"]: notifies only the notifications with these IDs

​
Example: Notify Only One Specific Webhook

Step 1: Get the notification id from the customer configs endpoint: 
curl -sS -X GET "$API_URL/customer-configs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"
Look for the id field in pipelineNotifications array. Step 2: Trigger execution with notificationIds 
WEBHOOK_NOTIFICATION_ID="YOUR_NOTIFICATION_ID"

curl -sS -X POST "$API_URL/executions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"applicationId\": \"YOUR_APPLICATION_ID\",
    \"planId\": \"YOUR_PLAN_ID\",
    \"environment\": \"YOUR_ENVIRONMENT\",
    \"provider\": \"PLAYWRIGHT\",
    \"browser\": {\"name\": \"CHROMIUM\"},
    \"suiteSlugs\": [\"YOUR_SUITE_SLUG\"],
    \"notificationIds\": [\"$WEBHOOK_NOTIFICATION_ID\"]
  }"

​
Next Steps