Cheat-Sheet

Quick reference guides and sheet in one page

Scenario definition

Describe your users behaviour

Scenario

scenario

Declares a new scenario

scenario(name)

name is the scenario name in the reports

Base structures

exec

Execution Step

exec(action)

The action that will be executed at this step.

exec(chain...)

Inserts the chain(s) at this point of the scenario

exec(Session => Session)

Perform an operation upon the session at this step

group

Group related requests together

group(groupName){chain}

Actions from chain are part of the group named groupName

pause

Declares a fixed or random pause in the scenario

pause(dur unit)

The pause will last duration

pause(duration, timeunit)

Declares a pause duration with a specific timeunit

pause(dur unit, dur unit)

Declares a pause duration randomly selected between the two durations

pause(duration, duration, timeunit)

Declares a pause randomly selected between the two durations with a specific time timeunit

pace

Pause which adjusts its wait time depending on how long the chained action took

pace(dur unit)

The pause will last duration

pace(duration, timeunit)

Declares a pause duration with a specific timeunit

pace(dur unit, dur unit)

Declares a pause duration randomly selected between the two durations

pace(duration, duration, timeunit)

Declares a pause randomly selected between the two durations with a specific time timeunit

rendezVous

Pauses users until all other users have reached the rendez-vous point

rendezVous(userNumber)

Number of users to wait for

Loops

repeat

Repeats a part of the scenario for a given number of times

repeat(times){chain}

The chain is repeated the specified number of times

repeat(times, counterName){chain}

The chain is repeated the specified number of times with a forced counter name

during

Repeats a part of the scenario for a given duration

during(dur unit){chain}

The chain is repeated for at least dur unit

during(dur unit, counterName){chain}

Same as above with forced counter name

asLongAs

Repeats a part of the scenario as long as a condition holds

asLongAs(condition){chain}

The chain is repeated as long as the condition is satisfied

asLongAs(condition, counterName){chain}

Same as above with forced counter name

foreach

Repeats a part of the scenario for each element of a sequence

foreach(sequence, elementName){chain}

The chain is repeated for every element in the sequence and the current element is stored in the Session under the elementName key

foreach(sequence, elementName, counterName){chain}

Same as above with forced counter name

doWhile

Similar to asLongAs but the condition is evaluated after the loop

doWhile(condition){chain}

The chain is repeated as long as the condition is satisfied

doWhile(condition, counterName){chain}

Same as above with forced counter name

asLongAsDuring

Similar to asLongAs but with an extra duration condition

asLongAsDuring(condition, duration, counterName){chain}

The chain is repeated as long as the condition is satisfied and the duration is not reached

doWhileDuring

Similar to doWhile but with an extra duration condition

doWhileDuring(condition, duration, counterName){chain}

The chain is repeated as long as the condition is satisfied and the duration is not reached

forever

Repeats a part of the scenario forever

forever(counterName){chain}

The chain is repeated forever. Forcing the counter name with counterName is optional

Conditions

doIf

Executes a chain when a condition is satisfied

doIf(condition){chain}

If the result of the condition is true, then chain is executed.

doIf(Session => Boolean){chain}

If the result of the function Session => Boolean is true, then chain is executed.

doIfEquals

Executes a chain when two values are equal

doIfEquals(expected, actual){chain}

If expected equals actual, then chain is executed

doIfOrElse

Executes a chain when a condition is satisfied, another if not

doIfOrElse(condition){chain}{otherChain}

If the result of the condition is true, then chain is executed, else otherChain is executed.

doIfOrElse(Session => Boolean){chain}{otherChain}

If the result of the function Session => Boolean is true, then chain is executed, else otherChain is executed.

doIfEqualsOrElse

Executes a chain when two values are equal, another if not

doIfEqualsOrElse(expected, actual){chain}{otherChain}

If expected equals actual, then chain is executed, else otherChain is executed.

doSwitch

Executes a chain based on a key

doSwitch(key){switch}

Switch is selected through the matching of a key with the evaluation of the passed expression. If no switch is selected, switch is bypassed.

doSwitchOrElse

Executes a chain based on a key or a fallback chain

doSwitchOrElse(key){switch}{chain}

Switch is selected through the matching of a key with the evaluation of the passed expression. If no switch is selected, chain is executed

randomSwitch

Current user will continue in one of the specified weighted chains. Can be used to simulate simple Markov chains

randomSwitch(Map[_,Chain])

The Map contains the distribution of the randomSwitch. Each chain is weighted with a percentage. Make sure the sum of weights does not exceed 100.

randomSwitchOrElse

Current user will continue in one of the specified weighted chains. Can be used to simulate simple Markov chains. Fallback available if no switch is selected

randomSwitchOrElse(Map[_,Chain]){chain}

The Map contains the distribution of the randomSwitch. Each chain is weighted with a percentage. Make sure the sum of weights does not exceed 100. If no switch is selected then chain is executed.

uniformRandomSwitch

Current user will continue in one of the uniform distributed chains. Can be used to simulate simple Markov chains

uniformRandomSwitch(chains...)

The list of chains.

roundRobinSwitch

A round-robin strategy is used to determine the chain to be executed.

roundRobinSwitch(chains...)

The list of chains.

Errors handling

tryMax

Retries a chain until it succeeds

tryMax(times){chain}

chain will be repeated until either all checks in it are OK; or the chain has been repeated times times.

exitBlockOnFail

Stops block execution if a check fails

exitBlockOnFail{chain}

If a check in chain fails, its execution is stopped and the scenario continues.

exitHere

Exit the scenario at this point.

exitHereIf

Exit the scenario at this point if the condition holds.

exitHereIf(condition: Expression[Boolean])

Exit if the condition evaluates to true

exitHereIfFailed

Exit the scenario at this point if this virtual user encountered an error during execution.

Simulation configuration

Tune your simulation

Time

pauses

Allows to configure pauses. Can also be defined at the scenario level

pauses(disablePauses)

Disable the pauses for the simulation

pauses(constantPauses)

Default value. Durations are precisely those filled in the pause(duration) elements.

pauses(exponentialPauses)

Pause durations are on average those filled in the pause(duration) elements and follow an exponential distribution.

pauses(customPauses(pauseDur))

Pauses durations are computed by the provided pauseDur. In this case the filled duration is bypassed

pauses(uniformPauses(plusOrMinus))

Pause durations are on average those filled in the pause(duration) elements and follow an uniform distribution.

maxDuration

Set a duration limit on your simulation

maxDuration(maxDuration)

The maximum duration of the simulation

Throttling

throttle

Allows to reason in terms of request per second and not in terms of users. Can also be defined at the scenario level. Throttle can take one to many building blocks described below.

Example:

setUp(...)
  .throttle(
    reachRps(100) in (10 seconds),
    holdFor(10 minute)
  )
throttle(reachRps(target) in (time unit))

Target a throughput with a ramp in a given time

throttle(jumpToRps(target))

Jump immediately to a given targeted throughput

throttle(holdFor(duration))

Hold the current throughput for a given duration

Feeder definition

Inject data in your scenario

Feeder types

csv

Declares a feeder from a CSV file

csv(fileName)

fileName is the name of the file under the resources folder containing the comma separated values to be injected

tsv

Declares a feeder from a TSV file

tsv(fileName)

fileName is the name of the file under the resources folder containing the tabulation separated values to be injected

ssv

Declares a feeder from a SSV file

ssv(fileName)

fileName is the name of the file under the resources folder containing the semi-colon separated values to be injected

jsonFile

Declares a feeder from a JSON file

jsonFile(fileName)

fileName is the name of the file under the resources folder containing JSON file to be injected

jsonUrl

Declares a feeder from a JSON url

jsonUrl(url)

url is the url returning the JSON array to be injected

jdbcFeeder

Declares a feeder from database records

jdbcFeeder(dbURL,user,pass,sql)

The feeder will load its values thanks to the sql request made on the database located at the JDBC URL dbURL as user/pass.
Note that you need to include the right JDBC4 driver in the classpath (lib folder if using the bundle)

redisFeeder
redisFeeder(pool, key)

This feeder loads its values from a Redis pool and stores them under key in the session.

Feeder options

batch

Load data by chunks of 200 records instead of loading all the data in memory (local file based feeders only)

batch(bufferSize)

Load data by chunks of bufferSize records instead of loading all the data in memory (local file based feeders only)

unzip

Decompress feeder file that is compressed with zip or gzip

shard Gatling Enterprise only

Distribute data amongst nodes when running a cluster of injectors

readRecords

Return the feeder content as a Seq[Map[String, Any]]

Feeder strategies

queue

This is the default strategy (you don't have to specify it). It takes the values in the feeder as in a queue. If the queue is not long enough, you'll get an error at execution.

random

This strategy chooses values randomly in the feeder. In contrast to a shuffle strategy the same values can be chosen several times.

circular

This strategy takes the values of the feeder in their order, and when it reaches the last, it returns to the first one.

shuffle

This strategy shuffles the values in the feeder but then works like the queue strategy.

Injection profile

Control how users are injected in your scenario

Open injection steps

atOnceUsers

Injects a specific number of users at the same time

atOnceUsers(nbUsers)

Injects nbUsers

rampUsers

Injects a given number of users with a linear ramp during a given duration

rampUsers(nbUsers) during(dur unit)

Injects nbUsers during a duration.

Example:

rampUsers(10) during(5 seconds)
constantUsersPerSec

Injects users at a constant rate, defined in users per second, during a given duration

constantUsersPerSec(nbUsers) during(dur unit)

Injects nbUsers each second for duration.

Example:

constantUsersPerSec(10) during(5 seconds)
rampUsersPerSec

Injects users from starting rate to target rate, defined in users per second, during a given duration

rampUsersPerSec(rate1) to (rate2) during(dur unit)

Injects users from starting rate1 to target rate2, defined in users per second, during a given duration.

Example:

rampUsersPerSec(10) to(20) during(10 minutes)
heavisideUsers

Injects a given number of users following a smooth approximation stretched to a duration

heavisideUsers(nbUsers) during(dur unit)

Injects a given number of users following a smooth approximation of the Heaviside step function stretched to a given duration

nothingFor

Pauses for a specific duration

nothingFor(dur unit)

Pause for a given duration

incrementUsersPerSec New!

Meta DSL to write open increment tests (succession of several increasing levels)

incrementUsersPerSec(incrementUsersPerSec)
  .times(numberOfSteps)
  .eachLevelLasting(levelDuration)
  .separatedByRampsLasting(rampDuration)
  .startingFrom(initialUsersPerSec)

Inject a succession of numberOfSteps levels each one during levelDuration and increasing the number of users per sec by incrementUsersPerSec starting from zero or the optional initialUsersPerSec and separated by optional ramps lasting rampDuration

Closed injection steps

constantConcurrentUsers

Maintain a constant number of concurrent users

constantConcurrentUsers(nbUsers) during(duration)

Maintain nbUsers for duration

rampConcurrentUsers

Scale number of concurrent users

rampConcurrentUsers(fromNbUsers) to(toNbUsers) during(duration)

Scale from fromNbUsers to toNbUsers during duration

incrementConcurrentUsers New!

Meta DSL to write closed increment tests (succession of several increasing levels)

incrementConcurrentUsers(incrementConcurrentUsers)
  .times(numberOfSteps)
  .eachLevelLasting(levelDuration)
  .separatedByRampsLasting(rampDuration)
  .startingFrom(initialConcurrentUsers)

Inject a succession of numberOfSteps levels each one during levelDuration and increasing the number of users per sec by incrementConcurrentUsers starting from zero or the optional initialConcurrentUsers and separated by optional ramps lasting rampDuration

Assertions

Check that your results match your expectations

Assertions

assertions

Declare the assertions on your simulation

assertions(assertions)

The assertions your simulation will be checked against

Scopes

global

Use statistics calculated from all requests

forAll

Use statistics calculated for each individual request.

details

Use statistics calculated from a group or a request

details(path)

The request or group path

Statistics

responseTime

Target the response time in milliseconds

allRequests

Target the number of requests

failedRequests

Target the number of failed requests

successfulRequests

Target the number of successful requests

requestsPerSec

Target the rate of requests per second

Response time selectors

min

Perform the assertion on the minimum of the stat

max

Perform the assertion on the maximum of the stat

mean

Perform the assertion on the mean of the stat

stdDev

Perform the assertion on the standard deviation of the stat

percentile1

Perform the assertion on the first percentile of the stat

percentile2

Perform the assertion on the second percentile of the stat

percentile3

Perform the assertion on the third percentile of the stat

percentile4

Perform the assertion on the fourth percentile of the stat

percentile

Perform the assertion on the given percentile of the stat

percentile(value)

The double value of percentile rank, between 0 and 100

Count selectors

percent

Use the value as a percentage between 0 and 100

count

Perform the assertion on the count of requests

Assertions conditions

lt

Check that the value of the statistic is less than the threshold

lt(threshold)

the statistic's higher bound

lte

Check that the value of the statistic is less than or equal to the threshold

lte(threshold)

the statistic's higher bound

gt

Check that the value of the statistic is greater than the threshold

gt(threshold)

the statistic's lower bound

gte

Check that the value of the statistic is greater than or equal to the threshold

gte(threshold)

the statistic's lower bound

between

Check that the value of the statistic is between two thresholds

between(thresholdMin, thresholdMax)

the statistic's bounds

between(thresholdMin,thresholdMax, inclusive = false)

the statistic's bounds, excluded

around

Check that the value of the metric is around a target value plus or minus a given margin.

around(value, margin)

the statistic's target and bounds margin

around(value, margin, inclusive = false)

the statistic's bounds, excluded

deviatesAround

Check that metric is around a target value plus or minus a given relative margin

deviatesAround(value, relativeMargin)

the statistic's target and bounds margin

deviatesAround(thresholdMin, thresholdMax, inclusive = false)

the statistic's bounds, excluded

is

Check that the value of the statistic is equal to the given value

is(value)

the value the statistic must be equal to

in

Check that the value of statistic is in a sequence

in(sequence)

the sequence the statistic has to be in

HTTP Action

Define the HTTP requests sent in your scenario

HTTP

http

Declares an HTTP request

http(name)

name is the request name in the reports

HTTP verb

get

Sets the HTTP method to GET

get(url)

Sets the url of the HTTP request

post

Sets the HTTP method to POST

post(url)

Sets the url of the HTTP request

put

Sets the HTTP method to PUT

put(url)

Sets the url of the HTTP request

delete

Sets the HTTP method to DELETE

delete(url)

Sets the url of the HTTP request

head

Sets the HTTP method to HEAD

head(url)

Sets the url of the HTTP request

patch

Sets the HTTP method to PATCH

patch(url)

Sets the url of the HTTP request

options

Sets the HTTP method to OPTIONS

options(url)

Sets the url of the HTTP request

httpRequest

Support for custom HTTP methods

httpRequest(method, url)

Executes method on url

HTTP options

queryParam

Adds a query parameter to the URL

queryParam(key, value)

http://example.tld?key=value

multivaluedQueryParam

Adds a query parameter to the URL with multiple values

multivaluedQueryParam(key, value...)

http://example.tld?key=value1&key=value2&key=value3...

queryParamsSeq

Adds multiple query parameters to the URL

queryParamsSeq((key, value)...)

http://example.tld?key1=value1&key2=value2&key3=value3...

queryParamsMap

Adds multiple query parameters to the URL

queryParamsMap(Map[key -> value])

http://example.tld?key1=value1&key2=value2&key3=value3...

header

Adds a header to the request.

header(key, value)

Adds key: value as header

headers

Adds several headers to the request.

headers(Map[key, value])

Adds every tuple key: value of the map as header

ignoreProtocolHeaders

Ignore default headers that were defined on the HttpProtocol

requestTimeout

Override the requestTimeout defined in the global configuration

requestTimeout(timeout)

A FiniteDuration, eg 3 minutes

sign

Pass a `SignatureCalculator` to sign the request.

sign(signatureCalculator)

Sign the request, typically add a new Authorization header based on request data

signWithOAuth1

Sign the request with OAuth1.

signWithOAuth1(consumerKey, clientSharedSecret, token, tokenSecret)

Sign the request with OAuth1

basicAuth

Sets the credentials for BASIC authentication

basicAuth(user, password)

Will authenticate as user with password

digestAuth

Sets the credentials for DIGEST authentication

digestAuth(user, password)

Will authenticate as user with password

ntlmAuth

Sets the credentials for NTLM authentication

ntlmAuth(user, password)

Will authenticate as user with password

authRealm

Generic method to add authentication

authRealm(Realm)

Takes a Realm instance

resources

Allows to fetch resources in parallel in order to emulate the behaviour of a real web browser

resources(request...)

Multiple requests to get resources

disableUrlEncoding

Disable URLEncoding if you're sure the urls you feed to Gatling are already properly encoded.

silent

Forces the request to be silent A silent request is issued but not logged nor reported

notSilent

Forces the request to NOT be silent, whatever's defined at protocol level. A silent request is issued but not logged nor reported

HTTP body

body

Adds a body from a resource to the request

body(RawFileBody(path))

Uploads a file as is from the path

body(ELFileBody(path))

Parses, resolves and then uploads a file containing Gatling EL from the path

body(StringBody(string))

Sets a string

body(ByteArrayBody(bytes))

Sets the body from a bytes array

body(InputStreamBody(stream))

Sets the body from an input stream

body(PebbleBody(path))

Parses, resolves and then uploads a Pebble template from the path

bodyPart

Add a multi-part body from a resource to the request

bodyPart(RawFileBodyPart(path))

Uploads a file as is from the path

bodyPart(ELFileBodyPart(path))

Parses, resolves and then uploads a file containing Gatling EL from the path

bodyPart(StringBodyPart(string))

Sets a string

bodyPart(ByteArrayBodyPart(bytes))

Sets the body from a bytes array

bodyPart(PebbleBodyPart(path))

Parses, resolves and then uploads a Pebble template from the path

formParam

Adds a form parameter to the request body

formParam(key, value)

Where key is the name and value is a string

formParam(HttpParam)

Where HttpParam is an instance of HttpParam

multivaluedFormParam

Adds a form parameter to the request body with multiple values

multivaluedFormParam(key, value...)

Where key is the name of one parameter and value can be a list

formParamSeq

Adds multiple form parameters to the request body

formParamSeq((key, value)...)

Where you can have multiple tuples of key and value

formParamMap

Adds multiple form parameters to the request body

formParamMap(Map[key -> value])

Where you can have a map of multiple key and value

form

Adds a form to the request body

form(Map[key -> Seq[value]])

Typically saved by a form check

processRequestBody

Allows to process the request body before it is sent to the wire

processRequestBody(Body => Body)

Takes a function to transform the request body

transformResponse

Allows to process the response before it is sent to the checks pipeline.

transformResponse((Session => Response) => Validation[Response]))

Takes a function to transform the Response, possibly based on data from the Session

formUpload

Provides a multi-part encoded request when you need to upload a file corresponding to a form text value.

Example:

Email attachment
formUpload(key, filePath)

Where key is the name of the field and filePath a path to a file located in resources

Checks

Verifying server responses

Check

check

Declare every check that should apply on the action

check(check...)

Every check you need to make on the response from the server

ignoreProtocolChecks

Ignore default checks that were defined on the HttpProtocol

name
name(name)

Use name to compute error message when check fails

CheckIf

checkIf

Enslave check execution to a condition

checkIf(condition: Expression[Boolean])(thenCheck: Check)

Only perform thenCheck if condition evaluates to true

checkIf(condition: (Response, Session) => Validation[Boolean])(thenCheck: Check)

Only perform thenCheck if condition return true

Check extractors

find

Specifies that only one value matching the check definition must be extracted

If used as find check will be applied on the first value found. Note that this is the default behaviour, you don't have to specify it.

find(occurrence)

Gets the occurrence-th value that matches the check definition.

findAll

Specifies that every value matching the check definition should be extracted for verification. The resulting type is a list of extracted values.

findRandom

Fetches random matches.

If used as findRandom fetches one single match, returns a single value.

findRandom(num: Int)

Fetches a given number of occurrences, returns a Seq.

findRandom(num: Int, failIfLess: Boolean)

Same as above, but fails if the number of actual matches is less than num.

count

The check will be applied on the size of the list returned by findall

HTTP checks

status

Check the HTTP status code of the response.

currentLocation

Check the url of the landing response.

header

Check the value of a given HTTP header of the response.

header(headerName)

The check will be applied on the header corresponding to headerName

header(Session => String)

Same as above, except that the header name is given by the Session => String function.

headerRegex

Apply a regular expression on value of a given HTTP header of the response.

headerRegex(headerName, pattern)

The check will be applied on the headers headerName whose value match the provided pattern.

headerRegex(Session => String)

Same as above, except that the header name is given by the Session => String function.

responseTimeInMillis

Return the response time of this request in milliseconds.

bodyString

Return the full response body String.

bodyBytes

Return the full response body byte array.

bodyStream

Return an InputStream of the full response body bytes.

substring

Look for occurrences of a given String in the response body String

substring(expression)

Extraction will look for expression indices.

regex

Apply a regular expression, possibly with capture groups, on the response body String.

regex(expression)

Extraction will use a regular expression defined by expression.

xpath

Apply an XPath expression on the response body String.

xpath(expression)

Extraction will use an XPath expression defined by expression

xpath(expression, namespaces)

If you want to use namespaces in your XPATH expression, you should specify them. The namespaces are specified thanks to a Map[prefix,uri]:
Map('c' -> 'http://core', 'f' -> 'http://format').

xpath(Session => String)

The expression can be expressed as a Session => String function (with namespaces also)

jsonPath

Apply a JsonPath expression on the response body String.

jsonPath(expression)

jsonPath is similar to XPATH, but for JSON encoded data.

jsonpJsonPath

Apply a JsonPath expression on the JSONP value of the response body String.

jsonpJsonPath(expression)

jsonpJsonPath is similar to jsonPath, but for JSONP

jmesPath

Apply a JMESPath expression on the response body String.

jmesPath(expression)

JMESPath is similar to XPATH, but for JSON encoded data.

jsonpJmesPath

Apply a JMESPath expression on the JSONP value of the response body String.

jsonpJmesPath(expression)

jsonpJmesPath is similar to jmesPath, but for JSONP

css

Apply a CSS selector on the response body String.

css(expression)

Uses the css selector to extract the value to be checked.

css(expression, attr)

Same as above, except that the extracted value is the attr of the selected node.

form

Capture an HTML form in the response body String.

form(expression)

Uses the css selector to extract the all the field values of an HTML form.

md5

Compute the md5 checksum of the response body.

sha1

Compute the sha1 checksum of the response body.

Check transformer

transform

Transform extracted data before verification.

transform(A => B)

This function is optional. It can be useful sometimes to apply a transformation on the extracted values before validating them. In this function, type A is the type of the find operation. Type B is whatever you want it to be (could be a case class for example)

transformWithSession

Transform extracted data before verification.

transformWithSession((A, Session) => B)

Same as transform, but with read access to the current Session.

transformOption

Transform extracted data before verification.

transformOption(Option[A] => Validation[Option[B]])

Gives full control over the extracted result, even providing a default value

transformOptionWithSession

Transform extracted data before verification.

transformOptionWithSession((Option[A], Session) => Validation[Option[B]])

Same as transformOption, but with read access to the current Session.

Check verifiers

is

Verify extracted value is equal to expected one.

is(expected)

if the captured (or transformed) value is equal to expected the check will succeed; it will fail otherwise

not

Verify extracted value is different from to expected one.

not(expected)

If the captured (or transformed) value is different than expected the check will succeed; it will fail otherwise

exists

Verify extracted value exists. This is the default verification (it does not need to be specified)

notExists

Verify extracted value does not exists.

in

Verify extracted value belongs to a specific set of values.

in(sequence)

If the captured (or transformed) value is included in the sequence the check will succeed; it will fail otherwise

optional

Noop, never fail.

isNull

Verify extracted value is null (typically JSON null).

notNull

Verify extracted value is not null (typically JSON null).

Check saver

saveAs

If the check succeeds, store in the Session the extracted value(s).

saveAs(key)

Extracted values get stored in the Session with the key key.

HTTP Protocol

Mutualize your scenario's code and tune the behaviour of Gatling's HTTP client

Protocol

http

Entry point of your HTTP protocol

Urls

baseUrl

Sets the base URL of all relative URLs of the scenario on which the configuration is applied

baseUrl(url)

The url that will be appended to all relative URLs (ie: not starting with http)

baseUrls

Same as baseUrl with client-based load balancing.

baseUrls(url...)

Each url will be used randomly to implement client load-balancing.

virtualHost

Overrides the default computed virtual host

virtualHost(name)

Eg: GET https://mobile.github.com/gatling/gatling instead of GET https://www.github.com/gatling/gatling

Proxy

proxy

Declares a proxy for all HTTP requetes of the scenario on which the configuration is applied

proxy(Proxy)

The requests will pass throught the proxy located within the Proxy object

noProxyFor

Disables the proxy for a certain list of hosts

noProxyFor(hosts)

The hosts ignoring the proxy

httpsPort

Uses this if Gatling should use the proxy for HTTPS also

httpsPort(port)

The HTTPS port of the proxy

credentials

If your proxy requires BASIC authentication you can set the credentials with this method

credentials(username,password)

The requests will be sent as the user username/password

socks4

If this proxy is a SOCKS4 one

socks5

If this proxy is a SOCKS5 one

Headers

acceptHeader

Sets the Accept header for all requests

acceptHeader(value)

The value of the header.

acceptCharsetHeader

Sets the Accept-Charset header for all requests

acceptCharsetHeader(value)

The value of the header

acceptEncodingHeader

Sets the Accept-Encoding header for all requests

acceptEncodingHeader(value)

The value of the header

acceptLanguageHeader

Sets the Accept-Language header for all requests

acceptLanguageHeader(value)

The value of the header

authorizationHeader

Sets the Authorization header for all requests

authorizationHeader(value)

The value of the header

connectionHeader

Sets the Connection header for all requests

connectionHeader(value)

The value of the header

contentTypeHeader

Sets the Content-Type header for all requests

contentTypeHeader(value)

The value of the header

doNotTrackHeader

Sets the DNT header for all requests

doNotTrackHeader(value)

The value of the header.

userAgentHeader

Sets the User-Agent header for all requests

userAgentHeader(value)

The value of the header

Options

disableFollowRedirect

Forces the HTTP engine not to follow the redirects. You can also disable it globally on the HttpProtocol

maxRedirects

Avoids infinite redirection loops by specifying a number max of redirects

maxRedirects(max)

Where max is the number of max redirects

disableAutomaticReferer

Forces Gatling not to set the referer of the requests

disableWarmUp

Disables the warm up request

warmUp

Sets the URL used by Gatling to warm up the HTTP engine

warmUp(url)

A valid and accessible url

inferHtmlResources

Allows to fetch resources in parallel in order to emulate the behaviour of a real web browser

inferHtmlResources(WhiteList)

Fetch all resources matching a pattern in the white list

inferHtmlResources(WhiteList, BlackList)

Fetch all resources matching a pattern in the white list excepting those in the black list

inferHtmlResources(Filters)

More generic version taking any kind of filters

nameInferredHtmlResourcesAfterUrlTail

Name requests after the resource's url tail (after last ``/``) (default)

nameInferredHtmlResourcesAfterUrlTail(WhiteList)

Fetch all resources matching a pattern in the white list

nameInferredHtmlResourcesAfterUrlTail(WhiteList, BlackList)

Fetch all resources matching a pattern in the white list excepting those in the black list

nameInferredHtmlResourcesAfterUrlTail(Filters)

More generic version taking any kind of filters

nameInferredHtmlResourcesAfterPath

Name requests after the resource's path

nameInferredHtmlResourcesAfterAbsoluteUrl

Name requests after the resource's absolute url

nameInferredHtmlResourcesAfterRelativeUrl

Name requests after the resource's relative url

nameInferredHtmlResourcesAfterLastPathElement

Name requests after the resource's last path element

nameInferredHtmlResources

Name requests with a custom strategy

nameInferredHtmlResources(Uri => String)

A function to generate the name out of the Uri

maxConnectionsPerHost

Sets the maximum concurrent connections per host per virtual user. Predefined parameters are available through methods such as maxConnectionsPerHostLikeFirefox...

maxConnectionsPerHost(max)

Where max is the number of maximum connections

shareConnections

Allows to share connections among users

enableHttp2

Enable HTTP/2 experimental support

http2PriorKnowledge
http2PriorKnowledge(Map[String, Boolean])

If virtual users already know if some hosts support HTTP/2 or not

asyncNameResolution

Use async name resolver instead Java's blocking one.

perUserNameResolution

Use per virtual user name resolver instead of a global one. Only enabled if asyncNameResolution is enabled.

hostNameAliases

Configure IP aliases to bypass DNS resolution

hostNameAliases(Map[String, List[String]])

Map of IP adresses by hostname

localAddress

Binds the sockets from a specific local address instead of the default one

localAddress(InetAddress)

Address String that will be turned ino a InetAddress

localAddresses

Binds the sockets from a list of specific local addresses instead of the default one

localAddresses(InetAddress...)

Address Strings that will be turned into InetAddresses

useAllLocalAddresses

Binds the sockets from all available local addresses

Address Strings that will be turned into InetAddresses

perUserKeyManagerFactory

Configure a specific javax.net.ssl.KeyManagerFactory per virtual user

perUserKeyManagerFactory(Long => javax.net.ssl.KeyManagerFactory)

Input is the virtual user's id

disableCaching

Disables caching features for some http headers and ETag

disableUrlEncoding

Disable URLEncoding if you're sure the urls you feed to Gatling are already properly encoded.

silentUri

Silence requests that match the pattern A silent request is issued but not logged nor reported

silentUri(String)

A regular expression pattern to match request urls

silentResources

Silence resource requests A silent request is issued but not logged nor reported

basicAuth

Sets the credentials for BASIC authentication

basicAuth(user, password)

Will authenticate as user with password

digestAuth

Sets the credentials for DIGEST authentication

digestAuth(user, password)

Will authenticate as user with password

ntlmAuth

Sets the credentials for NTLM authentication

ntlmAuth(user, password)

Will authenticate as user with password

authRealm

Generic method to add authentication

authRealm(Realm)

Takes a Realm instance

WebSockets

Define the WebSocket requests sent in your scenario

WebSocket

ws

Declares an WebSocket request

ws(requestName)

Name of the request

Commons

wsName

Allows to deal with several WebSockets per virtual user

wsName(requestName)

Gives the requests a name and pass this name on each ws operation

connect

Connects a WebSocket

connect(url)

Enables communication to the given url

onConnected

Pass a chain of actions to be performed on (re-)connecting.

onConnected(chain)

A chain of actions

close

Closes a WebSocket

sendText

Sends a String message

sendText(stringMessage)

Send stringMessage as a string

sendBytes

Sends a byte[] message

sendBytes(bytesMessage)

Send bytesMessage as a bytes array

Checks

await

Creates a blocking check

await(timeout)

The timeout if check doesn't completes in due time

await(checks)

The checks applied on expected server messages

checkTextMessage

Expect a WebSocket Text frame that would be validated against some criteria

checkTextMessage(name)

The name of the expected message to be displayed in response times and failures

checkBinaryMessage

Expect a WebSocket Binary frame that would be validated against some criteria

checkBinaryMessage(name)

The name of the expected message to be displayed in response times and failures

silent

Make a check silent so that it has no influence on stats

Configuration

wsBaseUrl

Serves as root that will be prepended to all relative WebSocket urls

wsBaseUrl(url)

Where url is the root url

wsBaseUrls

Serves as round-robin roots that will be prepended to all relative WebSocket urls

wsBaseUrls(url...)

Where url are the root urls

wsReconnect

Automatically reconnect a WebSocket that would have been closed by someone else than the client

wsMaxReconnects

Sets a limit on the number of times a WebSocket will be automatically reconnected

wsMaxReconnects(count)

Where count is the number of maximum reconnections url

SSE (Server Sent Events)

Define the SSE requests sent in your scenario

SSE

sse

Declares an SSE request

sse(requestName)

Name of the request

Commons

sseName

Allows to deal with several SSE streams per virtual user

sseName(requestName)

Gives the requests a name and pass this name on each SSE operation

connect

Connect a SSE stream

connect(url)

Enables communication to the given url

close

Close a SSE stream

JMS

Define the JMS requests sent in your scenario

Start

jms

Declares an JMS request

jms(requestName)

Name of the request

Commons

requestReply

Sets the messaging implementation to request/reply

send

Sets the messaging implementation to send

queue

Defines a target destination

queue(name: Expression[String])

Where name is the name of the queue

destination

Defines a target destination

destination(destination)

Where destination is an instance of JmsDestination

replyQueue

Defines a reply destination

replyQueue(name: Expression[String])

Where name is the name of the queue

replyDestination

Defines a reply destination

replyDestination(destination)

Where destination is an instance of JmsDestination

trackerQueue

On default gatling tracks the replies on the replyQueue. Optionally you can overwrite this destination with the parameter trackerQueue

trackerQueue(destination)

Where destination is an instance of JmsDestination

trackerDestination

On default gatling tracks the replies on the replyDestination. Optionally you can overwrite this destination with the parameter trackerDestination

trackerDestination(destination)

Where destination is an instance of JmsDestination

noJmsReplyTo

Don't populate JMSReplyTo message field

selector

Defines a JMS message selector

selector(selector)

Where selector is the selector

textMessage

Sends a text message

textMessage(textMessage)

Where textMessage is a string

bytesMessage

Sends a byte message

bytesMessage(bytesMessage)

Where bytesMessage is a byte array

mapMessage

Sends a map message

mapMessage(mapMessage)

Where mapMessage is a map

objectMessage

Sends an object message

objectMessage(objectMessage)

Where objectMessage is an object implementing JSerializable

property

Sends additional property

property(key, value)

Sets value as an object property key

jmsType

Set message's JMS type

jmsType(value)

Sets value as a JMSType

Checks

simpleCheck

Allows to check a message

simpleCheck(function)

Where function takes a Message and returns a Boolean

xpath

Allows to check a TextMessage with XPath

xpath(expression)

Where expression is an XPath expression

Protocol Configuration

jms

Entry point of your JMS configuration

Connecting

connectionFactoryName Required

Set the name of the ConnectionFactory to use

connectionFactoryName(name)

where name is a string

url Required

Set the URL of the queue to connect to.

url(url)

where url is a string

contextFactory Required

Set the name of the JNDI ContextFactory to use.

contextFactory(contextFactory)

where contextFactory is a string

credentials

Set the credentials used for the queues JNDI lookup

credentials(username, password)

the username and password to use as credentials

disableAnonymousConnect

Use credentials for opening connections too

listenerThreadCount

Number of consumers that will listen to incoming messages on the tracker/reply queue

listenerThreadCount(listenerThreadCount)

The number of consumers

replyTimeout
replyTimeout(duration)

the reply timeout in millis

Delivery modes

useNonPersistentDeliveryMode

Use JMS' non-persistent delivery mode (active by default)

usePersistentDeliveryMode

Use JMS' persistent delivery mode

Message matching

matchByMessageId

Match request and response using JMS's MessageID

matchByCorrelationId

Match request and response using JMS's CorrelationID

messageMatcher

Match request and response using a custom strategy

messageMatcher(messageMatcher)

an implementation of JmsMessageMatcher, specifying how the requestId and responseId are retrieved from the JMS Message

MQTT

 Gatling Enterprise only

Define the MQTT requests sent in your scenario

Start

mqtt

Declares an MQTT request

mqtt(requestName)

Name of the request

Commons

subscribe
subscribe(topic)

Subscribe to a topic

publish
publish(topic).message(body)

Publish a message with regular Body APIto a topic

expect

Set a non-blocking check

expect(duration)

Expect a matching reply message with duration

expect(duration, topic)

Expect a matching reply message with duration from topic topic

expect(duration, topic).check(check)

Validate received message against check using regulare Check API.

await

Set a blocking check

await(duration)

Expect a matching reply message with duration

await(duration, topic)

Expect a matching reply message with duration from topic topic

await(duration, topic).check(check)

Validate received message against check using regulare Check API.

waitForMessages
waitForMessages.timeout(duration)

Wait for all pending check to complete

Protocol Configuration

mqtt

Entry point of your MQTT configuration

mqttVersion_3_1

Use protocol version 3.1

mqttVersion_3_1_1

Use protocol version 3.1.1

broker
broker(hostname, port)

Use hostname andport for broker address

useTls
useTls(boolean)

Enable TLS

clientId
clientId(id)

Set id as MQTT clientId

cleanSession
cleanSession(boolean)

Clean session when connecting

credentials
credentials(userName, password)

Use (userName, password) credentials for connecting

keepAlive
keepAlive(duration)

Set connection keep-alive as duration seconds

qosAtMostOnce

Use at-most-once QoS

qosAtLeastOnce

Use at-least-once QoS

qosExactlyOnce

Use exactly-once QoS

retain
retain(boolean)

Enable or disable retain

lastWill
lastWill(LastWilltopic, willMessage).qosAtLeastOnce.retain(boolean)

Define last will

reconnectAttemptsMax
reconnectAttemptsMax(number)

Try to reconnect number times max

reconnectDelay
reconnectDelay(delay)

Wait delay millis before reconnecting

reconnectBackoffMultiplier
reconnectBackoffMultiplier(multiplier)

Use multiplier to compure actual reconnect delay

resendDelay
resendDelay(delay)

Wait delay millis before resending message

resendBackoffMultiplier
resendBackoffMultiplier(multiplier)

Use multiplier to compure actual resend delay

timeoutCheckInterval
timeoutCheckInterval(duration)

Check every duration for timed out checks

correlateBy
correlateBy(check)

Use check for extracting correlationId from sent and received messages

Edit this page on GitHub