|
| 1 | +# Functions |
| 2 | + |
| 3 | +TeaPie provides a lightweight function system for generating dynamic values in scripts and `.http` files. |
| 4 | + |
| 5 | +## Function Naming Rules |
| 6 | + |
| 7 | +- Must start with `$` |
| 8 | +- Allowed characters: letters, digits, `_`, `.`, `$`, `-` |
| 9 | +- Pattern used by parser: `^\$[a-zA-Z0-9_.$-]*$` |
| 10 | +- Function names are case-sensitive. |
| 11 | +- Function notation in `.http` files follows: `{{(\$.*)}}` |
| 12 | + |
| 13 | +## Function Levels |
| 14 | + |
| 15 | +TeaPie supports two levels of functions, determining visibility and resolution order: |
| 16 | + |
| 17 | +| Level | Scope & Behavior | |
| 18 | +|------|-------------------| |
| 19 | +| Default | Built-in functions available to all test cases and collections. | |
| 20 | +| Custom | User-registered functions that live for the current collection run. | |
| 21 | + |
| 22 | +### Function Resolution Order |
| 23 | + |
| 24 | +Functions are resolved in this order: |
| 25 | + |
| 26 | +1. Default Functions |
| 27 | +2. Custom Functions |
| 28 | + |
| 29 | +>The first match is executed. |
| 30 | +
|
| 31 | +--- |
| 32 | + |
| 33 | +## Using Functions in HTTP Files |
| 34 | + |
| 35 | +Syntax (no parentheses, no commas; max 2 arguments): |
| 36 | + |
| 37 | +- `{{$functionName}}` |
| 38 | +- `{{$functionName arg1}}` |
| 39 | +- `{{$functionName arg1 arg2}}` |
| 40 | + |
| 41 | +Notes: |
| 42 | + |
| 43 | +- Arguments are whitespace-separated tokens (maximum two per function). |
| 44 | +- Use quotes for values with spaces: `{{$now "yyyy-MM-dd HH:mm"}}` |
| 45 | +- Both single and double quotes are supported. |
| 46 | +- Function names are case-sensitive. |
| 47 | +- Internally, arguments are tokenized using a command-line parser and converted to the target parameter types. |
| 48 | + |
| 49 | +Using together with Variables: |
| 50 | + |
| 51 | +- You can pass Variables as function arguments by embedding variable notation inside the function call. |
| 52 | +- Variable notation must follow variable rules (name pattern, `{{variableName}}`). |
| 53 | +- Examples: |
| 54 | + - `{{$add {{MyNumber}} 2}}` // passes variable MyNumber as first argument |
| 55 | + - `{{$upper "{{FullName}}"}}` // if the variable value may contain spaces, wrap it in quotes |
| 56 | +- You can also mix standalone variables and functions in the same line, e.g.: |
| 57 | + - `X-Trace-Id: {{RequestId}}-{{$guid}}` |
| 58 | + - `X-Date: {{$now "yyyyMMdd"}}-{{EnvironmentName}}` |
| 59 | + |
| 60 | +If a function is not found, TeaPie throws an error during resolution. |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Built-in Functions |
| 65 | + |
| 66 | +The following functions are available by default: |
| 67 | + |
| 68 | +| Name | Signature | Description | Example | |
| 69 | +|------|-----------|-------------|---------| |
| 70 | +| `$guid` | `Guid $guid()` | Generates a new GUID. | `{{$guid}}` | |
| 71 | +| `$now` | `string $now(string? format)` | Current local time formatted via `DateTime.ToString(format)`. If `format` is omitted, default formatting is used. | `{{$now "yyyy-MM-dd"}}` | |
| 72 | +| `$rand` | `double $rand()` | Random double in the range [0, 1). | `{{$rand}}` | |
| 73 | +| `$randomInt` | `int $randomInt(int min, int max)` | Random integer in the range [min, max). | `{{$randomInt 1 100}}` | |
| 74 | + |
| 75 | +Notes: |
| 76 | + |
| 77 | +- `$now` uses `DateTime.Now` and the same formatting behavior as `DateTime.ToString(string?)`. |
| 78 | + |
| 79 | +Example: |
| 80 | + |
| 81 | +``` http |
| 82 | +# Generate values with functions |
| 83 | +POST https://example.com/api/items |
| 84 | +Content-Type: application/json |
| 85 | +
|
| 86 | +{ |
| 87 | + "id": "{{$guid}}", |
| 88 | + "createdAt": "{{$now "yyyy-MM-dd'T'HH:mm:ss"}}", |
| 89 | + "score": {{$randomInt 10 20}}, |
| 90 | + "ratio": {{$rand}} |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## Working with Functions in C\# |
| 97 | + |
| 98 | +Access functions through the `TeaPie` instance (`tp`). |
| 99 | + |
| 100 | +### **2️⃣ Registering via TeaPie** |
| 101 | + |
| 102 | +TeaPie supports registering functions with 0–2 parameters (maximum two arguments). |
| 103 | + |
| 104 | +``` cs |
| 105 | +// 0-arg |
| 106 | +tp.RegisterFunction("$buildNumber", () => Environment.GetEnvironmentVariable("BUILD_NUMBER") ?? "local"); |
| 107 | + |
| 108 | +// 1-arg |
| 109 | +tp.RegisterFunction("$upper", (string s) => s.ToUpperInvariant()); |
| 110 | + |
| 111 | +// 2-arg (maximum) |
| 112 | +tp.RegisterFunction("$add", (int a, int b) => a + b); |
| 113 | +``` |
| 114 | + |
| 115 | +### **1️⃣ Use them in `.http` files** |
| 116 | + |
| 117 | +``` http |
| 118 | +{{$upper "hello"}} |
| 119 | +{{$add 40 2}} |
| 120 | +``` |
| 121 | + |
| 122 | +### **3️⃣ Executing via TeaPie** |
| 123 | + |
| 124 | +```cs |
| 125 | +var id = tp.ExecFunction<Guid>("$guid"); |
| 126 | +var timeStamp = tp.ExecFunction<string>("$now", "yyyy-MM-dd"); |
| 127 | +var sum = tp.ExecFunction<int>("$add", 2, 3); |
| 128 | +``` |
| 129 | + |
| 130 | +>If a function is not found or execution fails, TeaPie throws an error during resolution. |
| 131 | +
|
| 132 | +--- |
| 133 | + |
| 134 | +## Argument Conversion |
| 135 | + |
| 136 | +- Arguments from `.http` files are strings |
| 137 | +- TeaPie converts them to expected parameter types using .NET conversion (`Convert.ChangeType(...)`) |
| 138 | + - Works for common primitives (int, double, bool, DateTime, etc.) |
| 139 | + - Uses the current culture during parsing |
| 140 | +- If conversion fails, execution throws an exception |
| 141 | + |
| 142 | +>Tip: Prefer culture-invariant formats in `.http` files for dates and decimals when needed. |
0 commit comments