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.

Core Keywords​

  • param - Add individual query parameters to URLs
  • params - Set multiple query parameters at once using JSON
  • form field - Add individual form fields for URL-encoded POST requests
  • form fields - Set multiple form fields at once using JSON

Keywords​

param - Query Parameters​

Add individual query parameters to URLs:

Gherkin
Feature: Query parameters

Background:
  * url 'https://jsonplaceholder.typicode.com'
  * def pageSize = 5
  * def userId = 1

Scenario: Basic query parameter
  Given path 'posts'
  And param _limit = 10
  When method get
  Then status 200

Scenario: Parameters with variables
  Given path 'posts'
  And param _limit = pageSize
  And param userId = userId
  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.

Key Points
  • Query parameters are appended to URLs as ?key=value&key2=value2
  • Variables and expressions are supported
  • Special characters are automatically URL-encoded
Gherkin
Feature: Query parameters

Scenario: Multi-value array parameters
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'comments'
  And param postId = ['1', '2', '3']
  When method get
  Then status 200

Arrays create repeated parameters: ?postId=1&postId=2&postId=3

form field - URL-Encoded Form Data​

Send form data as application/x-www-form-urlencoded content. Karate automatically sets the Content-Type header and encodes the data:

Gherkin
Feature: Form field handling

Scenario: Login form
  Given url 'https://httpbin.org'
  And path 'post'
  And form field username = 'testuser'
  And form field password = 'secret123'
  And form field remember = true
  When method post
  Then status 200

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

Gherkin
Feature: Form field handling

Background:
  * url 'https://httpbin.org'

Scenario: Dynamic form data
  * def credentials = { username: 'testuser', password: 'secret123', clientId: 'app-123' }
  Given path 'post'
  And form field username = credentials.username
  And form field password = credentials.password
  And form field client_id = credentials.clientId
  When method post
  Then status 200

Scenario: Multi-value form field
  Given path 'post'
  And form field interests = ['sports', 'music', 'technology']
  When method post
  Then status 200

Multi-Param Keywords​

params - Multiple Query Parameters​

Set multiple parameters at once using JSON:

Gherkin
Feature: Multiple parameters

Background:
  * url 'https://jsonplaceholder.typicode.com'

Scenario: Bulk parameter assignment
  Given path 'posts'
  * params { userId: 1, _limit: 10, _sort: 'title', _order: 'asc' }
  When method get
  Then status 200

Scenario: Dynamic parameter object
  * def searchCriteria = { userId: 1, _limit: 5 }
  Given path 'posts'
  * params searchCriteria
  When method get
  Then status 200

Scenario: Conditional parameters
  * def env = karate.env || 'dev'
  * def paramObject = { userId: 1 }
  * if (env != 'prod') paramObject._limit = 20
  Given path 'posts'
  * 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:

Gherkin
Feature: Multiple form fields

Background:
  * url 'https://httpbin.org'

Scenario: Registration form
  Given path 'post'
  * form fields { username: 'newuser', password: 'securepass123', email: 'newuser@example.com', firstName: 'John', lastName: 'Doe', acceptTerms: true }
  When method post
  Then status 200

Scenario: Form with inline data
  * def userData = { username: 'johndoe', password: 'secret', email: 'john@example.com' }
  Given path 'post'
  * form fields userData
  When method post
  Then status 200

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

Advanced: Special Character Encoding​

Karate automatically URL-encodes special characters in parameters:

Gherkin
Feature: Parameter encoding

Scenario: Special character handling
  Given url 'https://httpbin.org'
  And path 'get'
  And param query = 'user name with spaces'
  And param filter = 'created_date: 2024-01-01'
  And param tags = ['tag with spaces', 'normal-tag']
  When method get
  Then status 200

Null and Empty Values​

Gherkin
Feature: Null parameter handling

Scenario: Null value filtering
  * def searchParams = { userId: 1, _limit: null, _start: '', _sort: 'title' }
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'posts'
  * 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:

Gherkin
Feature: Parameter types

Scenario: Query parameters for filtering
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'posts'
  And param _page = 1
  And param _limit = 10
  And param userId = 1
  When method get
  Then status 200

Use form field for POST authentication and form submissions:

Gherkin
Feature: Parameter types

Scenario: Form fields for authentication
  Given url 'https://httpbin.org'
  And path 'post'
  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:

Gherkin
Feature: Parameter types

Scenario: Mixed parameter types
  Given url 'https://httpbin.org'
  And path 'post'
  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