Skip to main content

HTTP REQUESTS

Request Parameters

Configure query parameters and form data with automatic URL encoding, supporting both individual and bulk parameter assignments for dynamic API testing.

Benefits of Request Parameters​

  • Individual assignment: Set parameters one at a time with param and form field keywords
  • Bulk operations: Configure multiple parameters using JSON with params and form fields
  • Automatic encoding: Special characters, spaces, and arrays handled automatically
  • Dynamic testing: Null values ignored for flexible conditional parameter logic

Keywords that Set Key-Value Pairs​

param - Query Parameters​

Add individual query parameters to URLs:

Feature: Query parameters

Scenario: Basic query parameter
Given url baseUrl
And path 'users'
And param limit = 10
When method get
Then status 200

The param keyword adds query strings to your URL. The ? and & symbols are automatically inserted.

Use param for Query Strings

Always use param for query strings, never path. The ? character in path gets URL-encoded to %3F.

See Making Requests for details.

Feature: Query parameters

Scenario: Parameters with variables
Given url baseUrl
And path 'users'
* def pageSize = 25
* def userId = 123
And param limit = pageSize
And param filter = 'user_id:' + userId
When method get
Then status 200
Key Points
  • Query parameters are appended to URLs as ?key=value&key2=value2
  • Variables and expressions are supported
  • Special characters are automatically URL-encoded
Feature: Query parameters

Scenario: Multi-value array parameters
Given url baseUrl
And path 'search'
And param tags = ['important', 'urgent', 'customer']
And param category = 'electronics'
And param minPrice = 100
And param maxPrice = 1000
When method get
Then status 200

Arrays create repeated parameters: ?tags=important&tags=urgent&tags=customer

form field - URL-Encoded Form Data​

Add form fields for URL-encoded POST requests:

Feature: Form field handling

Scenario: Login form
Given url baseUrl
And path 'auth/login'
And form field username = 'testuser'
And form field password = 'secret123'
And form field remember = true
When method post
Then status 200
And match response.token == '#string'

The Content-Type header is automatically set to application/x-www-form-urlencoded when using form field.

Feature: Form field handling

Scenario: Dynamic form data
* def credentials = read('login-credentials.json')
Given url baseUrl
And path 'login'
And form field username = credentials.username
And form field password = credentials.password
And form field client_id = appConfig.clientId
When method post
Then status 200

Multi-Param Keywords​

params - Multiple Query Parameters​

Set multiple parameters at once using JSON:

Feature: Multiple parameters

Scenario: Bulk parameter assignment
Given url baseUrl
And path 'search'
* params { q: 'laptop', category: 'electronics', minPrice: 500, maxPrice: 2000, sort: 'price', order: 'asc' }
When method get
Then status 200
Feature: Multiple parameters

Scenario: Dynamic parameter object
* def searchCriteria = { query: 'smartphone', brand: ['apple', 'samsung', 'google'], inStock: true, limit: 20 }
Given url baseUrl
And path 'products'
* params searchCriteria
When method get
Then status 200
Feature: Multiple parameters

Scenario: Conditional parameters
* def env = karate.env || 'dev'
* def paramObject = { q: 'test' }
* if (env != 'prod') paramObject.debug = true
* if (env == 'dev') paramObject.verbose = true
Given url baseUrl
And path 'api/search'
* params paramObject
When method get
Then status 200
Null Value Handling

Null parameters are automatically ignored. Only defined values are included in the request.

form fields - Multiple Form Fields​

Set multiple form fields at once using JSON:

Feature: Multiple form fields

Scenario: Registration form
Given url baseUrl
And path 'auth/register'
* form fields { username: 'newuser', password: 'securepass123', email: 'newuser@example.com', firstName: 'John', lastName: 'Doe', acceptTerms: true }
When method post
Then status 201
Feature: Multiple form fields

Scenario: Form with external data
* def userData = read('registration-data.json')
Given url baseUrl
And path 'users/register'
* form fields userData
When method post
Then status 201
Feature: Multiple form fields

Scenario: Conditional form fields
* def baseForm = { username: 'test', password: 'secret' }
* def env = karate.env || 'dev'
* if (env == 'dev') baseForm.debugMode = true
* if (env != 'prod') baseForm.allowExperimentalFeatures = true
Given url baseUrl
And path 'login'
* form fields baseForm
When method post
Then status 200

Advanced: Special Character Encoding​

Karate automatically URL-encodes special characters in parameters:

Feature: Parameter encoding

Scenario: Special character handling
Given url baseUrl
And path 'search'
And param query = 'user name with spaces'
And param filter = 'created_date:"2024-01-01 10:30:00"'
And param complex = 'value with & and = signs'
And param tags = ['tag with spaces', 'tag&with&special', 'normal-tag']
When method get
Then status 200
Feature: Parameter encoding

Scenario: Date and time parameters
* def today = new Date()
* def todayStr = today.toISOString().split('T')[0]
* def timestamp = today.getTime()
Given url baseUrl
And path 'events'
And param startDate = todayStr
And param endDate = todayStr
And param timestamp = timestamp
And param timezone = 'UTC'
When method get
Then status 200

Null and Empty Values​

Feature: Null parameter handling

Scenario: Null value filtering
* def searchParams = { query: 'laptop', category: null, minPrice: '', inStock: true }
Given url baseUrl
And path 'search'
* params searchParams
When method get
Then status 200

Null values are ignored, but empty strings are preserved in the request.

Query Parameters vs Form Data​

Use param for GET requests and filtering:

Feature: Parameter types

Scenario: Query parameters for filtering
Given url baseUrl
And path 'users'
And param page = 1
And param limit = 50
And param status = 'active'
And param sort = 'created_date'
When method get
Then status 200

Use form field for POST authentication and form submissions:

Feature: Parameter types

Scenario: Form fields for authentication
Given url baseUrl
And path 'auth/login'
And form field username = 'testuser'
And form field password = 'secret'
And form field grant_type = 'password'
When method post
Then status 200

You can combine both in the same request:

Feature: Parameter types

Scenario: Mixed parameter types
Given url baseUrl
And path 'api/process'
And param version = '2.0'
And param format = 'json'
And form field action = 'validate'
And form field data = 'user input data'
When method post
Then status 200

Next Steps​

On This Page