# Testing and Debugging

Test your Custom Actions before they hit a live job site.

---

> **Note:** Custom Actions require a Builder plan or higher.
> [Upgrade to Builder](https://app.avcodex.com/plans)

## Built-in request tester

Test your actions inside the configuration interface.

### 1. Configure your action

Set up the URL, method, and parameters as usual.

### 2. Open the test panel

The test panel shows:

- Resolved URL with variables.
- Headers with substitutions.
- Body data structure.
- Query parameters.

### 3. Provide test values

For AI-generated parameters, enter test values:

```json
{
  "searchQuery": "boardroom 4 commissioning",
  "limit": 10,
  "includeArchived": false
}
```

### 4. Execute the test

Click **Test Request** to:

- Send the actual HTTP request.
- View response status.
- Inspect response body.
- Check response time.

### 5. Review results

```json
{
  "status": 200,
  "response": {
    "results": [
      {
        "id": 123,
        "title": "Boardroom 4 commissioning report"
      }
    ],
    "total": 42
  },
  "time": "234ms"
}
```

## Testing strategies

### Variable resolution

Verify all variables resolve correctly:

```bash
URL: {{var.BASE_URL}}/api/{{endpoint}}
Header: Bearer {{var.API_KEY}}

URL: https://api.example.com/api/rooms
Header: Bearer sk-abc123...
```

### Parameter types

Test each parameter type:

| Type    | Test value         | Expected      |
| ------- | ------------------ | ------------- |
| String  | `"boardroom-4"`    | Text value.   |
| Number  | `42`               | Numeric.      |
| Boolean | `true`             | Boolean.      |
| Object  | `{"key": "value"}` | JSON object.  |
| Array   | `[1, 2, 3]`        | JSON array.   |

### Edge cases

Test boundary conditions:

- **Empty values:** optional parameters.
- **Special characters:** in URLs and JSON strings.
- **Large payloads:** big objects or arrays.
- **Invalid inputs:** error handling.

## Common issues

### Authentication errors

**401 Unauthorized**

```json
{
  "error": "Invalid API key"
}
```

**Solution:** check your API key variable:

1. Verify the variable value.
2. Check header format (`Bearer`, `Basic`, etc.).
3. Use the secret type for sensitive values.

### CORS errors

**Browser console error**

```
Access to fetch at 'api.example.com' from origin 'app.avcodex.com' has been blocked by CORS policy
```

**Solution:** the API must allow requests from `app.avcodex.com`:

- Add `app.avcodex.com` to allowed origins.
- Or use a proxy endpoint.
- Or run the call server-side.

### Variable not resolving

**Issue:** `{{var.API_KEY}}` appears literally in the request.

**Debug steps**

1. Check the variable exists in the Variables tab.
2. Verify the exact name (case-sensitive).
3. Confirm the variable has a value.
4. Check syntax: `{{var.NAME}}`.

### JSON parse errors

**Issue:** body parameters not formatting correctly.

```json
// Bad
{
  "data": "{"nested": "value"}"
}

// Good
{
  "data": {
    "nested": "value"
  }
}
```

**Solution:** use the proper type (Object/Array) for nested data.

## Debug mode

Enable detailed logging for troubleshooting:

### Request details

View the exact request being sent:

```bash
POST https://api.example.com/endpoint
Headers:
  Authorization: Bearer [REDACTED]
  Content-Type: application/json
Body:
{
  "query": "boardroom 4",
  "filters": {
    "status": "active"
  }
}
```

### Response details

Inspect the full response:

```json
{
  "status": 200,
  "headers": {
    "content-type": "application/json",
    "x-request-id": "req_123"
  },
  "body": {
    "success": true,
    "data": [...]
  }
}
```

## Testing dependencies

For actions with dependencies:

### 1. Test prerequisites first

```bash
GET /api/me → Returns {"id": 123}

GET /api/users/123/details → Uses output from Action 1
```

### 2. Simulate dependency output

Test with mock values:

- Manually provide expected values.
- Verify parameter mapping.
- Check JSONPath selectors.

### 3. Test the full chain

In a conversation:

1. Trigger the first action.
2. Verify output is stored.
3. Trigger the dependent action.
4. Confirm the value passes through correctly.

## Performance testing

### Response times

Monitor action performance:

| Metric         | Good      | Warning     | Bad       |
| -------------- | --------- | ----------- | --------- |
| Response time  | <500ms    | 500-2000ms  | >2000ms   |
| Timeout        | -         | -           | 30s       |

### Optimization tips

1. **Use pagination** for large datasets.
2. **Cache responses** when appropriate.
3. **Minimize payload size**.
4. **Use specific field selection.**

## Error handling

### Graceful failures

Design actions to fail gracefully:

```json
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Room with ID 123 not found"
  }
}
```

### Retry logic

For transient failures:

- Network timeouts.
- Rate limiting.
- Temporary server errors.

### User-friendly messages

The agent receives error context and can relay it to the tech:

```json
{
  "error": "Unable to send email: recipient address invalid"
}
```

## Production checklist

Before going live:

### Security

- [ ] API keys in secret variables.
- [ ] HTTPS endpoints only.
- [ ] No sensitive data in URLs.
- [ ] Proper authentication headers.

### Reliability

- [ ] All parameters tested.
- [ ] Error responses handled.
- [ ] Dependencies verified.
- [ ] Timeouts configured.

### Performance

- [ ] Response times acceptable.
- [ ] Payload sizes optimized.
- [ ] Rate limits considered.
- [ ] Caching implemented.

### Documentation

- [ ] Clear action descriptions.
- [ ] AI instructions complete.
- [ ] Example values provided.
- [ ] Variable purposes documented.

## Troubleshooting guide

| Issue                    | Cause              | Solution                                    |
| ------------------------ | ------------------ | ------------------------------------------- |
| Variables not replaced   | Syntax error       | Check `{{var.NAME}}` format.                |
| Auth fails               | Wrong credentials  | Update variable value.                      |
| Timeout                  | Slow API           | Optimize endpoint or increase timeout.      |
| Wrong data               | Bad JSONPath       | Test path selector.                         |
| No response              | CORS or network    | Check API accessibility.                    |

## Next steps

- [View examples](/docs/custom-actions/examples)
- [Parameter configuration](/docs/custom-actions/parameter-configuration)
- [Manage variables](/docs/custom-actions/variables-and-secrets)

*AVCodex · Your AV expertise. Amplified by AI.*