@xano/developer-mcp 1.0.27 → 1.0.28

package/dist/xanoscript_docs_auto/testing.md

@@ -0,0 +1,574 @@
+---
+applyTo: "functions/**/*.xs,apis/**/*.xs"
+---
+
+# Testing
+
+Unit tests, mocks, and assertions in XanoScript.
+
+## Quick Reference
+
+```xs
+function "my_function" {
+  // ... implementation ...
+
+  test "test name" {
+    function.call {
+      input = {param: "value"}
+    } as $result
+
+    expect.to_equal {
+      input = $result
+      value = "expected"
+    }
+  }
+}
+```
+
+---
+
+## Test Block
+
+Add tests directly within functions:
+
+```xs
+function "add_numbers" {
+  input {
+    int a
+    int b
+  }
+  stack {
+    var $sum { value = $input.a + $input.b }
+  }
+  response = $sum
+
+  test "adds positive numbers" {
+    function.call {
+      input = {a: 2, b: 3}
+    } as $result
+
+    expect.to_equal {
+      input = $result
+      value = 5
+    }
+  }
+
+  test "adds negative numbers" {
+    function.call {
+      input = {a: -2, b: -3}
+    } as $result
+
+    expect.to_equal {
+      input = $result
+      value = -5
+    }
+  }
+
+  test "handles zero" {
+    function.call {
+      input = {a: 5, b: 0}
+    } as $result
+
+    expect.to_equal {
+      input = $result
+      value = 5
+    }
+  }
+}
+```
+
+---
+
+## Calling Functions in Tests
+
+### function.call
+
+Call the current function:
+
+```xs
+function.call {
+  input = {
+    name: "test",
+    value: 123
+  }
+} as $result
+```
+
+### With Mocks
+
+Override external calls:
+
+```xs
+test "handles database error" {
+  function.call {
+    input = {user_id: 1}
+    mock = {
+      "db.get user": null
+    }
+  } as $result
+
+  expect.to_be_null { input = $result }
+}
+```
+
+---
+
+## Assertions
+
+### Equality
+
+```xs
+expect.to_equal {
+  input = $result
+  value = "expected value"
+}
+
+expect.to_not_equal {
+  input = $result
+  value = "unexpected value"
+}
+```
+
+### Boolean
+
+```xs
+expect.to_be_true { input = $condition }
+
+expect.to_be_false { input = $condition }
+```
+
+### Null/Defined
+
+```xs
+expect.to_be_null { input = $value }
+
+expect.to_not_be_null { input = $value }
+
+expect.to_be_defined { input = $value }
+
+expect.to_not_be_defined { input = $value }
+```
+
+### Empty
+
+```xs
+expect.to_be_empty { input = $array }
+```
+
+### Contains
+
+```xs
+expect.to_contain {
+  input = $array
+  value = $item
+}
+```
+
+### String Assertions
+
+```xs
+expect.to_start_with {
+  input = $string
+  value = "prefix"
+}
+
+expect.to_end_with {
+  input = $string
+  value = "suffix"
+}
+
+expect.to_match {
+  input = $string
+  value = "^[A-Z]+$"  // Regex pattern
+}
+```
+
+### Numeric Comparisons
+
+```xs
+expect.to_be_greater_than {
+  input = $value
+  value = 10
+}
+
+expect.to_be_less_than {
+  input = $value
+  value = 100
+}
+
+expect.to_be_within {
+  input = $value
+  min = 0
+  max = 100
+}
+```
+
+### Date Assertions
+
+```xs
+expect.to_be_in_the_past { input = $timestamp }
+
+expect.to_be_in_the_future { input = $timestamp }
+```
+
+### Error Assertions
+
+```xs
+expect.to_throw {
+  run {
+    function.call {
+      input = {invalid: true}
+    }
+  }
+}
+```
+
+---
+
+## Mocking
+
+### Mock Database Calls
+
+```xs
+test "returns user profile" {
+  function.call {
+    input = {user_id: 1}
+    mock = {
+      "db.get user": {
+        id: 1,
+        name: "Test User",
+        email: "test@example.com"
+      }
+    }
+  } as $result
+
+  expect.to_equal {
+    input = $result.name
+    value = "Test User"
+  }
+}
+```
+
+### Mock Database Queries
+
+```xs
+test "returns filtered products" {
+  function.call {
+    input = {category: "electronics"}
+    mock = {
+      "db.query product": [
+        {id: 1, name: "Phone", price: 599},
+        {id: 2, name: "Laptop", price: 999}
+      ]
+    }
+  } as $result
+
+  expect.to_equal {
+    input = $result|count
+    value = 2
+  }
+}
+```
+
+### Mock API Calls
+
+```xs
+test "fetches external data" {
+  function.call {
+    input = {}
+    mock = {
+      "api.request": {
+        status: 200,
+        data: {items: [1, 2, 3]}
+      }
+    }
+  } as $result
+
+  expect.to_equal {
+    input = $result.items|count
+    value = 3
+  }
+}
+```
+
+### Mock Function Calls
+
+```xs
+test "uses helper function" {
+  function.call {
+    input = {value: 100}
+    mock = {
+      "function.run calculate_tax": 10
+    }
+  } as $result
+
+  expect.to_equal {
+    input = $result.total
+    value = 110
+  }
+}
+```
+
+---
+
+## Testing Patterns
+
+### Test Edge Cases
+
+```xs
+function "divide" {
+  input {
+    decimal a
+    decimal b
+  }
+  stack {
+    precondition ($input.b != 0) {
+      error_type = "inputerror"
+      error = "Cannot divide by zero"
+    }
+
+    var $result { value = $input.a / $input.b }
+  }
+  response = $result
+
+  test "divides numbers" {
+    function.call {
+      input = {a: 10, b: 2}
+    } as $result
+
+    expect.to_equal { input = $result, value = 5 }
+  }
+
+  test "handles decimals" {
+    function.call {
+      input = {a: 7, b: 2}
+    } as $result
+
+    expect.to_equal { input = $result, value = 3.5 }
+  }
+
+  test "throws on divide by zero" {
+    expect.to_throw {
+      run {
+        function.call {
+          input = {a: 10, b: 0}
+        }
+      }
+    }
+  }
+}
+```
+
+### Test Database Operations
+
+```xs
+function "get_user_orders" {
+  input {
+    int user_id
+  }
+  stack {
+    db.query order {
+      where = $db.order.user_id == $input.user_id
+      order_by = {field: "created_at", direction: "desc"}
+    } as $orders
+  }
+  response = $orders
+
+  test "returns orders for user" {
+    function.call {
+      input = {user_id: 1}
+      mock = {
+        "db.query order": [
+          {id: 1, user_id: 1, total: 100},
+          {id: 2, user_id: 1, total: 200}
+        ]
+      }
+    } as $result
+
+    expect.to_equal { input = $result|count, value = 2 }
+  }
+
+  test "returns empty for user with no orders" {
+    function.call {
+      input = {user_id: 999}
+      mock = {
+        "db.query order": []
+      }
+    } as $result
+
+    expect.to_be_empty { input = $result }
+  }
+}
+```
+
+### Test Conditional Logic
+
+```xs
+function "get_discount" {
+  input {
+    decimal total
+    text? coupon
+  }
+  stack {
+    var $discount { value = 0 }
+
+    // Volume discount
+    conditional {
+      if ($input.total >= 100) {
+        var.update $discount { value = 0.1 }
+      }
+    }
+
+    // Coupon discount
+    conditional {
+      if ($input.coupon == "SAVE20") {
+        var.update $discount { value = 0.2 }
+      }
+    }
+  }
+  response = $discount
+
+  test "no discount for small orders" {
+    function.call {
+      input = {total: 50}
+    } as $result
+
+    expect.to_equal { input = $result, value = 0 }
+  }
+
+  test "volume discount for large orders" {
+    function.call {
+      input = {total: 150}
+    } as $result
+
+    expect.to_equal { input = $result, value = 0.1 }
+  }
+
+  test "coupon discount overrides volume" {
+    function.call {
+      input = {total: 150, coupon: "SAVE20"}
+    } as $result
+
+    expect.to_equal { input = $result, value = 0.2 }
+  }
+}
+```
+
+---
+
+## Testing APIs
+
+```xs
+query "create_user" verb=POST {
+  input {
+    text name
+    email user_email
+  }
+  stack {
+    db.add user {
+      data = {
+        name: $input.name,
+        email: $input.user_email
+      }
+    } as $user
+  }
+  response = $user
+
+  test "creates user" {
+    function.call {
+      input = {name: "Test", user_email: "test@example.com"}
+      mock = {
+        "db.add user": {
+          id: 1,
+          name: "Test",
+          email: "test@example.com"
+        }
+      }
+    } as $result
+
+    expect.to_equal { input = $result.name, value = "Test" }
+    expect.to_equal { input = $result.email, value = "test@example.com" }
+  }
+}
+```
+
+---
+
+## Testing Tasks
+
+```xs
+task "daily_cleanup" {
+  stack {
+    db.bulk.delete session {
+      where = $db.session.expires_at < now
+    } as $deleted
+  }
+
+  test "deletes expired sessions" {
+    task.call {
+      mock = {
+        "db.bulk.delete session": {count: 5}
+      }
+    } as $result
+
+    expect.to_be_true { input = true }
+  }
+
+  schedule { ... }
+}
+```
+
+---
+
+## Best Practices
+
+### Name Tests Clearly
+
+```xs
+// Good: Describes behavior
+test "returns null for non-existent user" { ... }
+
+// Bad: Vague
+test "test 1" { ... }
+```
+
+### Test One Thing Per Test
+
+```xs
+// Good: Focused tests
+test "calculates subtotal" { ... }
+test "applies discount" { ... }
+test "adds tax" { ... }
+
+// Bad: Multiple assertions
+test "calculates order total" {
+  // Tests subtotal, discount, tax, and total
+}
+```
+
+### Use Meaningful Mock Data
+
+```xs
+// Good: Realistic data
+mock = {
+  "db.get user": {
+    id: 1,
+    name: "Jane Smith",
+    email: "jane@example.com",
+    created_at: "2024-01-15 10:30:00+0000"
+  }
+}
+
+// Bad: Minimal data
+mock = {
+  "db.get user": {id: 1}
+}
+```
+
+### Test Error Cases
+
+```xs
+test "handles missing user" { ... }
+test "rejects invalid input" { ... }
+test "handles API timeout" { ... }
+```