Parameterization

AngusTester provides the following 4 parameterization methods to meet different testing needs:
Variables: Define constant values that can be shared throughout the test
Datasets: Define a set of related parameters with dynamically changing values during testing
Mock Functions: Dynamically generate parameter values or random values
Sampling Extraction Variables: Extract values from previous sampling results for subsequent use

Variables

Define single reusable values referenced using {variable_name} format. Supports:

Static values
Values generated by Mock functions
Values extracted from HTTP/files/databases

📌 Important: Variable values are fixed before sampling execution and do not change during execution

Field Name	Type	Required	Length Limit	Description
`name`	string	Yes	<=100	Variable name
`description`	string	No	<=200	Variable description
`value`	string	No*	<=4096	Variable value (required for non-extracted variables), supports Mock functions like `@String(5,10)`
`passwordValue`	boolean	No	/	Whether it's a password value (hidden in UI if true)
`extraction`	object	Yes*	/	Extraction configuration (required for extracted variables), see Extraction Configuration below

Example: Static Variable

yaml

configuration:
  variables:
  - name: myUsername
    value: xcan

Example: Password Variable

yaml

configuration:
  variables:
  - name: myPassword
    value: 123456
    passwordValue: true

Example: Mock Function Variable

yaml

configuration:
  variables:
  - name: userId
    value: '@Uuid()'  # Generates new UUID each iteration

💡 Feature: Mock function variables remain constant within the same iteration, supporting resource CRUD testing
⚙️ Can disable iteration updates via updateVariableByIteration configuration (enabled by default)

Example: HTTP Extraction Variable

yaml

configuration:
  variables:
  - name: accessToken
    extraction: 
      source: HTTP
      method: JSON_PATH
      expression: $.data.access_token
      location: RESPONSE_BODY
      request:  # HTTP request configuration
        method: POST
        url: http://example.com/login
        body:
          rawContent: "{\n    \"username\":\"admin\",\n    \"password\":\"admin\"\n}"

✅ Advantage: Automatically updates time-sensitive data like tokens, avoiding manual maintenance

Example: File Extraction Variable

yaml

configuration:
  variables:
  - name: hobbies
    extraction: 
      source: FILE
      fileType: CSV
      path: /data/user.csv
      rowIndex: 3  # 4th row (0-based index)
      columnIndex: 2 # 3rd column

📝 Supported file formats: CSV/Excel

Example: Database Extraction Variable

yaml

configuration:
  variables:
  - name: userCount
    extraction: 
      source: JDBC
      select: SELECT count(*) FROM users
      datasource:
        type: MYSQL
        username: sample
        password: 123456
        jdbcUrl: jdbc:mysql://host:3306/db

Datasets

Define sets of related parameters (e.g., test data) referenced using {parameter_name}. Supports:

Static datasets
File extraction
JDBC extraction

🔄 Dynamic Feature: Parameter values change dynamically during execution

Field Name	Type	Required	Length Limit	Description
`name`	string	Yes	<=100	Dataset name
`description`	string	No	<=200	Dataset description
`parameters`	array[object]	No*	<=200	Parameter list (required for static datasets)
`extraction`	object	Yes*	/	Extraction configuration (required for extracted datasets)

Parameter Configuration

Field Name	Type	Required	Length Limit	Description
`name`	string	Yes	<=100	Parameter name
`value`	string	No*	<=4096	Parameter value (required for static parameters)

Example: Static Dataset

yaml

task:
  pipelines:
    - target: HTTP
      name: UpdateUserEmail              # Update user email
      request:
        method: PATCH
        url: http://example.com/api/v1/user/email
        body:
          rawContent: "{\"id\":\"{id}\",\"email\":\"{email}\"}"
      datasets:
      - name: UserData
        parameters:  # Define parameter columns
        - name: id
          value: '@Uuid()'  # Dynamically generate ID
        - name: age
          value: '@Email()' # Dynamically generate Email

Example: File Dataset

yaml

task:
  pipelines:
    - target: HTTP
      name: UpdateUserEmail              # Update user email
      request:
        method: PATCH
        url: http://example.com/api/v1/user/email
        body:
          rawContent: "{\"id\":\"{id}\",\"email\":\"{email}\"}"
      datasets:
      - name: CSVData
        parameters:  # Define parameter columns
        - name: id
        - name: email
        extraction:
          source: FILE
          fileType: CSV
          path: /data/users.csv

Example: Database Dataset

yaml

task:
  pipelines:
    - target: HTTP
      name: UpdateUserEmail              # Update user email
      request:
        method: PATCH
        url: http://example.com/api/v1/user/email
        body:
          rawContent: "{\"id\":\"{id}\",\"email\":\"{email}\"}"
      datasets:
        - name: DBData
          parameters:  # Define parameter columns
          - name: id
          - name: email
          extraction:                                 # Extraction configuration
            source: JDBC                              # Value source, fixed value: JDBC
            method: EXACT_VALUE                       # Extract values using exact value method
            datasource:                               # Datasource configuration
              type: MYSQL
              username: sample
              password: 123456
              jdbcUrl: jdbc:mysql://host:3306/db
            select: SELECT * FROM users               # SQL query for dataset values (no pagination needed, defaults to 5000 records per fetch)
            rowIndex: 0                               # Specify starting row (default 0)
            columnIndex: 0                            # Specify starting column (default 0)

Mock Functions

Generate dynamic values using @function_name() format, e.g., @Email() generates email addresses. Supports:

Text generation (names/addresses/IDs etc.)
Number generation (integers/decimals/ranges)
Date generation (dates/times/timestamps)

📚 See dedicated Mock Functions Documentation

Sampling Extraction Variables

Extract values from current sampling requests/responses for use in subsequent samplings

yaml

task:
  pipelines:
    - target: HTTP
      name: AddGroup               # Add group
      enabled: true
      request:
        method: POST
        url: http://example.com/api/v1/group
        body:
          rawContent: "[{\"code\":\"TestGroup\",\"name\":\"测试组\",\"remark\":\"\",\"\tagIds\":[]}]"
      variables:
        - source: HTTP_SAMPLING     # Value source, fixed value: HTTP_SAMPLING
          name: groupId             # Extract group ID from response: {"code":"S","msg":"成功","data":[{"id":"235027106575356558"}],"datetime":"2024-07-17 15:02:09","ext":{}}
          method: JSON_PATH
          expression: $.data.id
          location: RESPONSE_BODY
    - target: HTTP
      name: QueryGroup              # Query group
      enabled: true
      beforeName: ModifyGroup
      request:
        method: GET
        url: "http://example.com/api/v1/group/{id}"
        parameters:
          - name: id
            in: path
            enabled: true
            type: string
            value: "{groupId}"                      # Note: Reference sampling variable {groupId} in Path parameter

Extraction Configuration

AngusTester supports data extraction from five sources: text values, HTTP, HTTP sampling, files, and JDBC.

Common Extraction Parameters

Parameter	Type	Required	Limit	Description
`name`	string	Conditional	≤100 chars	Extraction identifier. Note: For sampling extraction variables, this serves as the variable name and is mandatory.
`method`	enum	Yes	-	Extraction method: `EXACT_VALUE`,`REGEX`, `JSON_PATH`,`X_PATH`
`expression`	string	Conditional	≤1024 chars	Extraction expression (required for non-exact value methods)
`matchItem`	integer	No	0-1024	Index position for multi-value matching
`defaultValue`	string	Yes	≤4096 chars	Default value when extraction fails
`source`	enum	Yes	-	Data source identifier: `VALUE`,`FILE`,`HTTP`, `HTTP_SAMPLING`,`JDBC`

Text Value Extraction (source=VALUE)

Extraction Note

Text value extraction directly extracts data from given text content.

Field Name	Type	Required	Length Limit	Description
`source`	enum	Yes	/	Extraction source, fixed value: `VALUE`. See "Matching Source (source)" for details.

Extraction Methods (method)

Method	Description	Use Cases
EXACT_VALUE	Exact value extraction Gets raw content directly without expression matching	- Full content extraction - Unformatted data processing
REGEX	Regular expression extraction Matches target data using regex patterns	- Text pattern matching - Unstructured data processing
JSON_PATH	JSON path extraction Uses JSONPath syntax to locate data in JSON structures	- JSON response parsing - API data extraction
X_PATH	XML path extraction Uses XPath syntax to locate data in XML documents	- XML file parsing - SOAP interface testing

Match Item (matchItem)

When expressions match multiple values or results are arrays, specifies which value to use as the expected result (0-based index up to 2000). Returns null if specified position doesn't exist. Merges multiple values when not specified.

Regex matching
- Match value:
  txt
```
hello, RegexExtraction! my phone number is 18888888888 and 13999999999.
```
- Expression: (1\d{10})
- Match result: ["18888888888","13999999999"]
- Match item:
  - Default (no position): Merged result "1888888888813999999999"
  - Position 0: "18888888888"
  - Position 1: "13999999999"
JSONPath matching
- Match value:
  json
```
{
  "store": {
    "book": [
      {"title": "Sayings of the Century", "price": 100},
      {"title": "Confucianism", "price": 200}
    ]
  }
}
```
- Expression: $.store.book[*]
- Match result: [{"title":"Sayings...","price":100},{"title":"confucianism","price":200}]
- Match item:
  - Default: Full array
  - Position 0: {"title":"Sayings...","price":100}
  - Position 1: {"title":"confucianism","price":200}
XPath matching
- Match value:
  xml
```
<persons>
  <person><age>30</age><interests>coding</interests><interests>basketball</interests><name>Angus1</name></person>
  <person><age>32</age><interests>coding</interests><name>Angus2</name></person>
</persons>
```
- Expression: /persons/person[age >= 30]
- Match result: "30codingbasketballAngus1", "32codingAngus2"
- Match item:
  - Default: Merged "30codingbasketballAngus132codingAngus2"
  - Position 0: "30codingbasketballAngus1"
  - Position 1: "32codingAngus2"

Matching Sources (source)

Source	Description	Use Cases
`VALUE`	Extract directly from text content	- Fixed text parsing - Expression validation - Simple data extraction
`FILE`	Extract from local/remote files	- Batch data processing - Test dataset loading - File format conversion
`HTTP`	Get data via API requests	- Preloading dynamic data - Authentication tokens - Cross-system integration
`HTTP_SAMPLING`	Real-time extraction from test API responses	- Chained API calls - Dynamic parameter passing - Contextual testing
`JDBC`	Extract from database queries	- Business data validation - Database status checks - Data-driven testing

File Extraction (source=FILE)

Extraction Note

File extraction reads structured data from local/remote files (CSV/Excel). Note: Both variables and datasets support this method.

Field Name	Type	Required	Length Limit	Description
`source`	enum	Yes	/	Extraction source, fixed value: `FILE`.
`fileType`	enum	Yes	/	File type, supports `CSV` and `EXCEL`, defaults to `CSV`.
`encoding`	string	/		File encoding
`quoteChar`	object	No	/	CSV quote character (default "") for fields containing special characters
`escapeChar`	object	No	/	CSV escape character (default "") for escaping special characters
`separatorChar`	object	No	/	CSV field separator (default ",")
`rowIndex`	integer	No	/	Starting row index (0-based, default 0)
`columnIndex`	integer	No	/	Starting column index (0-based, default 0)

yaml

extraction:                                 # Extraction config
  source: FILE                              # Fixed value: FILE
  name: Extract from csv file
  method: EXACT_VALUE                       # Exact value extraction
  fileType: CSV                             # CSV file
  path: /data/user.csv                      # File path
  encoding: UTF-8                           # File encoding
  quoteChar: '"'                            # Quote character
  escapeChar: \                             # Escape character
  separatorChar: ","                        # Separator
  rowIndex: 4                               # Starting row (0-based)
  columnIndex: 2                            # Starting column (0-based)

HTTP Extraction (source=HTTP)

Extraction Note

HTTP extraction extracts target data from API responses via predefined HTTP requests. Note: Variables support HTTP extraction; datasets do not.

Field Name	Type	Required	Length Limit	Description
`name`	string	No*	/	Extraction name (required as variable name for sampling extraction)
`method`	enum	Yes	/	Extraction method (see "Extraction Methods")
`expression`	string	Yes*	/	Extraction expression (required for REGEX/JSON_PATH/X_PATH)
`matchItem`	integer	No	/	Match item index for multi-value results
`defaultValue`	string	Yes	/	Default value when extraction fails
`source`	enum	Yes	/	Fixed value: `HTTP`
`location`	enum	Yes	/	Extraction location (see "Extraction Locations")
`parameterName`	string	No	/	Parameter name (required for header/query/path/form extractions)
`request`	object	No	/	HTTP request configuration

Extraction Locations (location)

Request data locations

Location	Description	Example
PATH_PARAMETER	URL path parameters	`/users/{user_id}`
QUERY_PARAMETER	URL query parameters	`?order_id=12345`
REQUEST_HEADER	HTTP request headers	`Authorization: Bearer token`
FORM_PARAMETER	Form parameters	`username=admin&password=123`
REQUEST_RAW_BODY	Raw request body	JSON/XML content

Response data locations

Location	Description	Example
RESPONSE_HEADER	HTTP response headers	`Set-Cookie: session_id=abc`
RESPONSE_BODY	Response body content	API JSON/XML data

yaml

extraction: 
  source: HTTP                                      # Source of extraction value, fixed value: HTTP  
  name: Extract access_token value                 
  method: JSON_PATH                                 # Method to extract value: JSON_PATH  
  expression: $.data.access_token                   # JSONPath extraction expression  
  defaultValue: a4b08effa7bf4bfb9579fb2fe96e1812    # Default value returned if extraction fails or expression is invalid  
  location: RESPONSE_BODY                           # Extraction location: from response body  
  request:                                          # HTTP request configuration  
    method: POST  
    url: http://example.com/user/signin  
    body:  
      rawContent: "{\n    \"username\":\"admin\",\n    \"password\":\"admin\"\n}"

HTTP Sampling Extraction (source=HTTP_SAMPLING)

Extraction Note

HTTP Sampling Extraction dynamically retrieves data from HTTP request/response contexts during test execution.

Field Name	Type	Required	Length Limit	Description
`source`	enum	Yes	/	Extraction source, fixed value: `HTTP_SAMPLING`.
`location`	enum	Yes	/	Extraction location. Refer to the "Extraction Location (location)" section below for supported conditions.
`parameterName`	string	No	/	Parameter name for extraction. Required when extracting from request headers, response headers, query parameters, path parameters, or form parameters.

yaml

variables:  
- source: HTTP_SAMPLING     # Source of extraction value, fixed value: HTTP_SAMPLING  
  name: groupId             # Extract from the current sampling response  
  method: JSON_PATH  
  expression: $.data.id  
  location: RESPONSE_BODY

JDBC Extraction (source=JDBC)

Extraction Note

JDBC Extraction retrieves field values from database result sets via SQL queries. Note: Both variables and datasets support this method.

Field Name	Type	Required	Length Limit	Description
`source`	enum	Yes	/	Extraction source, fixed value: `JDBC`.
`datasource`	object	Yes	/	Data source configuration. Refer to the "Data Source Configuration Parameters (storeDatasource)" section for details.
`select`	string	Yes	/	SQL SELECT statement for querying table data, max 1024 characters. Note: For dataset extraction, SELECT defaults to 5000 rows per query.
`rowIndex`	integer	No	/	Starting row index for reading parameter values (0-based). Note: If the first row is a header, typically start from index 1 (second row).
`columnIndex`	integer	No	/	Starting column index for reading parameters (0-based).

yaml

extraction:                                 # Extraction configuration  
  source: JDBC                              # Source of extraction value, fixed value: JDBC  
  name: Extract value from MYSQL database  
  method: EXACT_VALUE                       # Method to extract value: EXACT_VALUE  
  datasource:                               # Data source configuration  
    type: MYSQL  
    username: sample  
    password: 123456  
    jdbcUrl: jdbc:mysql://mysql01-sample.angusmock.cloud:3306/xcan_mockdata_sample  
  select: SELECT * FROM `user`              # SQL query for dataset values (no pagination needed; defaults to 5000 rows per fetch)  
  rowIndex: 0                               # Starting row index (default: 0, first row)  
  columnIndex: 0                            # Starting column index (default: 0, first column)

Tasks

Protocol Test

Parameterization

Variables

Datasets

Parameter Configuration

Mock Functions

Sampling Extraction Variables

Extraction Configuration

Common Extraction Parameters

Text Value Extraction (source=VALUE)

Extraction Methods (method)

Match Item (matchItem)

Matching Sources (source)

File Extraction (source=FILE)

HTTP Extraction (source=HTTP)

Extraction Locations (location)

HTTP Sampling Extraction (source=HTTP_SAMPLING)

JDBC Extraction (source=JDBC)

Tasks

Protocol Test

Parameterization ​

Variables ​

Datasets ​

Parameter Configuration ​

Mock Functions ​

Sampling Extraction Variables ​

Extraction Configuration ​

Common Extraction Parameters ​

Text Value Extraction (source=VALUE) ​

Extraction Methods (method) ​

Match Item (matchItem) ​

Matching Sources (source) ​

File Extraction (source=FILE) ​

HTTP Extraction (source=HTTP) ​

Extraction Locations (location) ​

HTTP Sampling Extraction (source=HTTP_SAMPLING) ​

JDBC Extraction (source=JDBC) ​

Parameterization

Variables

Datasets

Parameter Configuration

Mock Functions

Sampling Extraction Variables

Extraction Configuration

Common Extraction Parameters

Text Value Extraction (source=VALUE)

Extraction Methods (method)

Match Item (matchItem)

Matching Sources (source)

File Extraction (source=FILE)

HTTP Extraction (source=HTTP)

Extraction Locations (location)

HTTP Sampling Extraction (source=HTTP_SAMPLING)

JDBC Extraction (source=JDBC)