Documentation

Request extends RequestBase
in package

Application

The Request class represents a single HTTP request to be made by Artillery within the flow section of a scenario.

Tags

example

$getTarget = Artillery::request('get', '/inbox')
     ->setJson('client_id', '{{ id }}')
     ->addCapture('first_inbox_id', 'json', '$[0].id');

$postResponse = Artillery::request('post', '/inbox')
     ->setJsons(['user_id' => '{{ first_inbox_id }}', 'message' => 'Hello, world!']);

link

https://www.artillery.io/docs/guides/guides/http-reference

$request : mixed
addAfterResponse() : $this: Add a function or array of functions from the JavaScript file defined with Artillery::setProcessor to be executed after the response is received where the response can be inspected, and custom variables can be set.
addBeforeRequest() : $this: Add a function or array of functions from the JavaScript file defined with Artillery::setProcessor to be executed before the request is sent, where you can set headers or body dynamically.
addCapture() : $this: Adds a capture to the request to parse responses and re-use those values in subsequent requests as '{{ alias }}'.
addCaptures() : $this: Adds an array of capture objects to the request.
addExpect() : $this: Adds an expectation assertion to the request.
addExpects() : $this: Adds an array of expectation assertions to the request.
addMatch() : $this: Adds a matching statement to the request, similar to a capture but without an 'as' alias.
addMatches() : $this: Adds an array of matching statement to the request, similar to a capture but without an 'as' alias.
set() : $this: Set arbitrary data in the request, such as those from third party extension.
setAuth() : $this: If your request requires Basic HTTP authentication, set your username and password under the auth option.
setBody() : $this: Set the body of the request. This can be a string or an array (which will be stringified with JSON).
setCookie() : $this: Set a Cookie to send with the request. These will be merged with any cookies that have been set globally.
setCookies() : $this: Set an array of Cookies to send with the request. These will be merged with any cookies that have been set globally.
setFollowRedirect() : $this: Artillery follows redirects by default. To stop Artillery from following redirects, set this to false.
setForm() : $this: Set a URL-encoded form attribute (application/x-www-form-urlencoded).
setFormData() : $this: Set a Multipart/form-data form attribute (forms containing files, non-ASCII data, and binary data).
setFormDatas() : $this: Set an array of Multipart/form-data form attributes (forms containing files, non-ASCII data, and binary data).
setForms() : $this: Set an array of URL-encoded form attributes (application/x-www-form-urlencoded).
setGzip() : $this: Set gzip to true for Artillery to add an Accept-Encoding header to the request, and decode compressed responses encoded with gzip.
setHeader() : $this: Arbitrary header may be sent under the 'headers' option for a request.
setHeaders() : $this: Associative array of [name => value, ...] arbitrary headers may be sent under the 'headers' option for a request.
setIfTrue() : $this: The ifTrue option can execute a request in a flow only when meeting a condition.
setJson() : $this: Set a JSON field for the request. If called without parameters, it will initialize an empty JSON object '{ }'.
setJsons() : $this: Set an array of JSON fields for the request.
setMethod() : $this: Set the HTTP method to use for the request, e.g 'get', 'post', 'put', 'patch', 'delete'.
setQueryString() : $this: Set a query string for the request. This is equivalent to url?key=value.
setQueryStrings() : $this: Set an array of query strings for the request. ['page' => 1, 'limit' => 10] is equivalent to url?page=1&limit=10.
setRequest() : $this: Completely override the request data for this request.
setUrl() : $this: Set the URL to send the request to, it can be fully qualified or relative to the Artillery script target URL.

$request


    protected
        mixed
    $request
     = []

@internal

addAfterResponse()

Add a function or array of functions from the JavaScript file defined with Artillery::setProcessor to be executed after the response is received where the response can be inspected, and custom variables can be set.


    public
                    addAfterResponse(string|array<string|int, string> $function) : $this

Parameters

$function : string|array<string|int, string>: The function(s) to execute.

Return values

$this —

The current Request instance.

addBeforeRequest()

Add a function or array of functions from the JavaScript file defined with Artillery::setProcessor to be executed before the request is sent, where you can set headers or body dynamically.


    public
                    addBeforeRequest(string|array<string|int, string> $function) : $this

Parameters

$function : string|array<string|int, string>: The function(s) to execute.

Return values

$this —

The current Request instance.

addCapture()

Adds a capture to the request to parse responses and re-use those values in subsequent requests as '{{ alias }}'.


    public
                    addCapture(string $as, string $type, string $expression[, bool $strict = true ][, string|null $attr = null ][, int|string $index = null ]) : $this

Parameters

$as : string: Captured data alias.
$type : string
$expression : string: Capture expression.
$strict : bool = true: Whether to throw an error if the capture expression does not match anything.
$attr : string|null = null: If $type is 'selector': The name of the attribute whose value we want.
$index : int|string = null

Tags

description

The capture option must always have an as attribute, which names the value for use in subsequent requests. It also requires one of the following attributes:

json - Allows you to define a JSONPath expression.
xpath - Allows you to define an XPath expression.
regexp - Allows you to define a regular expression that gets passed to a RegExp constructor. A specific capturing group to return may be set with the group attribute (set to an integer index of the group in the regular expression). Flags for the regular expression may be set with the flags attribute.
header - Allows you to set the name of the response header whose value you want to capture.
selector - Allows you to define a Cheerio element selector. The attr attribute will contain the name of the attribute whose value we want. An optional index attribute may be set to a number to grab an element matching a selector at the specified index, "random" to grab an element at random, or "last" to grab the last matching element. If the index attribute is not specified, the first matching element will get captured.

example

// Cheerio element selector: $request->addCapture(as: "productUrl", type: "selector", expression: "a[class^=productLink]", index: "random", attr: "href")
// Xpath: $request->addCapture(as: "JourneyId", type: "xpath", expression: "(//Journey)[1]/JourneyId/text()")
// Header: $request->addCapture(as: "headerValue", type: "header", expression: "x-my-custom-header")
// Json:
$getIdRequest = Artillery::request('get', '/users')
   ->addCapture('first_id', 'json', '$[0].id');
$postMsgRequest = Artillery::request('post', '/inbox')
  ->setPayload(['id' => '{{ first_id }}', 'msg' => 'Hello world!']);

link

https://www.artillery.io/docs/guides/guides/http-reference#extracting-and-re-using-parts-of-a-response-request-chaining

Return values

$this —

The current Request instance.

addCaptures()

Adds an array of capture objects to the request.


    public
                    addCaptures(array<string|int, mixed> $captures) : $this

Parameters

$captures : array<string|int, mixed>

Tags

description

The capture option must always have an as attribute, which names the value for use in subsequent requests. It also requires one of the following attributes:

json - Allows you to define a JSONPath expression.
xpath - Allows you to define an XPath expression.
regexp - Allows you to define a regular expression that gets passed to a RegExp constructor. A specific capturing group to return may be set with the group attribute (set to an integer index of the group in the regular expression). Flags for the regular expression may be set with the flags attribute.
header - Allows you to set the name of the response header whose value you want to capture.
selector - Allows you to define a Cheerio element selector. The attr attribute will contain the name of the attribute whose value we want. An optional index attribute may be set to a number to grab an element matching a selector at the specified index, "random" to grab an element at random, or "last" to grab the last matching element. If the index attribute is not specified, the first matching element will get captured.

example

// Cheerio element selector: $request->addCapture(as: "productUrl", type: "selector", expression: "a[class^=productLink]", index: "random", attr: "href")
// Xpath: $request->addCapture(as: "JourneyId", type: "xpath", expression: "(//Journey)[1]/JourneyId/text()")
// Header: $request->addCapture(as: "headerValue", type: "header", expression: "x-my-custom-header")
// Json:
$getIdRequest = Artillery::request('get', '/users')
    ->addCaptures([
        ['as' => 'id', 'json' => '$[0].id'],
	       ['as' => 'name', 'json' => '$[0].name'],
    ]);

$postMsgRequest = Artillery::request('post', '/inbox')
  ->setPayload(['id' => '{{ id }}', 'msg' => 'Hello {{ name }}!']);

link

https://www.artillery.io/docs/guides/guides/http-reference#extracting-and-re-using-parts-of-a-response-request-chaining

Return values

$this —

The current Request instance.

addExpect()

Adds an expectation assertion to the request.


    public
                    addExpect(string $type, mixed $value[, mixed $equals = null ]) : $this

Parameters

$type : string
$value : mixed: The value(s) to expect.
$equals : mixed = null: Equals can be added after hasHeader and hasProperty to do an equality check.

Tags

description

Expectations are assertions that are checked after the request is made. If the assertion fails, the request is considered to have failed.
The built-in 'expect' plugin needs to be enabled with Artillery::setPlugin('expect') for this feature. Here's a list of the available expectations:
contentType, statusCode, notStatusCode: expectNotStatusCode, hasHeader, headerEquals, hasProperty, equals, matchesRegexp, notHasProperty, cdnHit.

example

npm i artillery-plugin-expect

$artillery->setPlugin('expect');
$ensureRequest = Artillery::request('get', '/users/1')
   ->addExpect('statusCode', [200, 201]);

link

https://www.artillery.io/docs/guides/plugins/plugin-expectations-assertions#expectations

link

https://www.artillery.io/docs/guides/plugins/plugin-expectations-assertions

Return values

$this —

The current Request instance.

addExpects()

Adds an array of expectation assertions to the request.


    public
                    addExpects(array<string|int, mixed> $expects) : $this

Parameters

$expects : array<string|int, mixed>

Tags

description

example

npm i artillery-plugin-expect

$artillery->setPlugin('expect');
$expectJson200 = [
    ['statusCode' => 200],
    ['contentType' => 'application/json'],
];
$ensureRequest = Artillery::request('get', '/users/1')
   ->addExpects($expectJson200);

link

https://www.artillery.io/docs/guides/plugins/plugin-expectations-assertions#expectations

link

https://www.artillery.io/docs/guides/plugins/plugin-expectations-assertions

Return values

$this —

The current Request instance.

addMatch()

Adds a matching statement to the request, similar to a capture but without an 'as' alias.


    public
                    addMatch(string $type, string $expression, mixed $value[, bool $strict = true ][, string $attr = null ][, int|string $index = null ]) : $this

Parameters

$type : string
$expression : string: The capture expression.
$value : mixed: The value to match against the capture.
$strict : bool = true
$attr : string = null
$index : int|string = null

Tags

example

$request = Artillery::request('get', '/users')
    ->addMatch('json', '$[0].name', 'John');

Return values

$this —

The current Request instance.

addMatches()

Adds an array of matching statement to the request, similar to a capture but without an 'as' alias.


    public
                    addMatches(array<string|int, mixed> $matches) : $this

Parameters

$matches : array<string|int, mixed>

Tags

example

$request = Artillery::request('get', '/users')
    ->addMatches([
        ['json' => '$[0].name', 'value' => 'John'],
        ['json' => '$[1].name', 'value' => 'Jane']
    ]);

Return values

$this —

The current Request instance.

set()

Set arbitrary data in the request, such as those from third party extension.


    public
                    set(string $key, mixed $data) : $this

Parameters

$key : string
$data : mixed: Arbitrary data to add to the request.

Tags

example

$artillery = Artillery::new()->setPlugin('something', ['some' => 'option']);
$request = Artillery::request('get', '/users/1')
    ->set('something', ['pluginAction' => 'values']);

Return values

$this —

The current Request instance.

setAuth()

If your request requires Basic HTTP authentication, set your username and password under the auth option.


    public
                    setAuth(string $user, string $pass) : $this

Parameters

$user : string: The username to use for authentication.
$pass : string: The password to use for authentication.

Return values

$this —

The current Request instance.

setBody()

Set the body of the request. This can be a string or an array (which will be stringified with JSON).


    public
                    setBody(mixed $body) : $this

Parameters

$body : mixed: The body of the request in arbitrary data.

Tags

example

$request->setBody('Hello world!');

Return values

$this —

The current Request instance.

setCookie()

Set a Cookie to send with the request. These will be merged with any cookies that have been set globally.


    public
                    setCookie(string $name, string $value) : $this

Parameters

$name : string: The name of the cookie to set.
$value : string: The value of the cookie to set.

Tags

example

$request->setCookie('session_id', '1234567890');

link

https://www.artillery.io/docs/guides/guides/http-reference#cookies

Return values

$this —

The current Request instance.

setCookies()

Set an array of Cookies to send with the request. These will be merged with any cookies that have been set globally.


    public
                    setCookies(array<string, string> $cookies) : $this

Parameters

$cookies : array<string, string>: An array of cookies to set.

Tags

example

$request->setCookies(['session_id' => '1234567890', 'name' => 'Geraldo']);

link

https://www.artillery.io/docs/guides/guides/http-reference#cookies

Return values

$this —

The current Request instance.

setFollowRedirect()

Artillery follows redirects by default. To stop Artillery from following redirects, set this to false.


    public
                    setFollowRedirect([bool $followRedirect = true ]) : $this

Parameters

$followRedirect : bool = true: If set to false, redirects will not be followed. Defaults to true.

Return values

$this —

The current Request instance.

setForm()

Set a URL-encoded form attribute (application/x-www-form-urlencoded).


    public
                    setForm(string $key, mixed $value) : $this

Parameters

$key : string: The key of the form data to set.
$value : mixed: The value of the form data to set.

Tags

example

$request = Artillery::request('post', '/submit')
    ->setForm('name', 'Swanson')
    ->setForm('vote', 'Hamburger');

link

https://www.artillery.io/docs/guides/guides/http-reference#url-encoded-forms-applicationx-www-form-urlencoded

Return values

$this —

The current Request instance.

setFormData()

Set a Multipart/form-data form attribute (forms containing files, non-ASCII data, and binary data).


    public
                    setFormData(string $key, mixed $value) : $this

Parameters

$key : string: The key of the form data to set.
$value : mixed: The value of the form data to set.

Return values

$this —

The current Request instance.

setFormDatas()

Set an array of Multipart/form-data form attributes (forms containing files, non-ASCII data, and binary data).


    public
                    setFormDatas(array<string|int, mixed> $formData) : $this

Parameters

$formData : array<string|int, mixed>: An array of form data to set.

Return values

$this —

The current Request instance.

setForms()

Set an array of URL-encoded form attributes (application/x-www-form-urlencoded).


    public
                    setForms(array<string|int, mixed> $form) : $this

Parameters

$form : array<string|int, mixed>: An array of form data to set. As [key => value, ...].

Tags

example

$request = Artillery::request('post', '/submit')
    ->setForms(['name' => 'Swanson', 'vote' => 'Hamburger']);

link

https://www.artillery.io/docs/guides/guides/http-reference#url-encoded-forms-applicationx-www-form-urlencoded

Return values

$this —

The current Request instance.

setGzip()

Set gzip to true for Artillery to add an Accept-Encoding header to the request, and decode compressed responses encoded with gzip.


    public
                    setGzip([bool $gzip = true ]) : $this

https://www.artillery.io/docs/guides/guides/http-reference#compressed-responses-gzip

Parameters

$gzip : bool = true: Whether to use gzip to decode/decompress the response.

Return values

$this —

The current Request instance.

setHeader()

Arbitrary header may be sent under the 'headers' option for a request.


    public
                    setHeader(string $key, string $value) : $this

Parameters

$key : string: The name of the header to set.
$value : string: The value of the header to set.

Tags

example

$request = Artillery::request()->setHeader('User-Agent', 'Mozilla/5.0 (Linux; Android 12; ...');

link

https://www.artillery.io/docs/guides/guides/http-reference#setting-headers

Return values

$this —

The current Request instance.

setHeaders()

Associative array of [name => value, ...] arbitrary headers may be sent under the 'headers' option for a request.


    public
                    setHeaders(array<string, string> $headers) : $this

Parameters

$headers : array<string, string>: A key-value array of headers to set.

Tags

example

$request = Artillery::request()->setHeaders(['User-Agent' => 'Mozilla/5.0 (Linux; Android 12; ...']);

link

https://www.artillery.io/docs/guides/guides/http-reference#setting-headers

Return values

$this —

The current Request instance.

setIfTrue()

The ifTrue option can execute a request in a flow only when meeting a condition.


    public
                    setIfTrue(string $expression) : $this

Parameters

$expression : string: The expression to evaluate.

Tags

example

$request = Artillery::request('get', '/pages/{{ pageNumber }}')
    ->setIfTrue('pageNumber < 10');

link

https://www.artillery.io/docs/guides/guides/http-reference#conditional-requests

Return values

$this —

The current Request instance.

setJson()

Set a JSON field for the request. If called without parameters, it will initialize an empty JSON object '{ }'.


    public
                    setJson([string|null $key = null ][, mixed $value = null ]) : $this

Parameters

$key : string|null = null: The name of the JSON field to set.
$value : mixed = null: The value of the JSON field to set.

Tags

example

$request = Artillery::request('post', '/submit')
    ->setJson('name', 'Swanson')
    ->setJson('vote', 'Hamburger');

link

https://www.artillery.io/docs/guides/guides/http-reference#get--post--put--patch--delete-requests

Return values

$this —

The current Request instance.

setJsons()

Set an array of JSON fields for the request.


    public
                    setJsons(array<string, mixed> $jsons) : $this

Parameters

$jsons : array<string, mixed>: An array of data to be stringified as JSON data for the request.

Tags

example

$request = Artillery::request('post', '/submit')
    ->setJsons([
        'name' => 'Swanson',
        'vote' => 'Hamburger']);

link

https://www.artillery.io/docs/guides/guides/http-reference#get--post--put--patch--delete-requests

Return values

$this —

The current Request instance.

setMethod()

Set the HTTP method to use for the request, e.g 'get', 'post', 'put', 'patch', 'delete'.


    public
                    setMethod(string $method) : $this

Parameters

$method : string: The HTTP method for this request.

Return values

$this —

The current Request instance.

setQueryString()

Set a query string for the request. This is equivalent to url?key=value.


    public
                    setQueryString(string $key, mixed $value) : $this

Parameters

$key : string: The key of the query string.
$value : mixed: The value of the query string.

Tags

example

$request->setQueryString('page', 1);

link

https://www.artillery.io/docs/guides/guides/http-reference#query-strings

Return values

$this —

The current Request instance.

setQueryStrings()

Set an array of query strings for the request. ['page' => 1, 'limit' => 10] is equivalent to url?page=1&limit=10.


    public
                    setQueryStrings(array<string|int, mixed> $qs) : $this

Parameters

$qs : array<string|int, mixed>

Tags

example

$request->setQueryStrings(['page' => 1, 'limit' => 10]);

link

https://www.artillery.io/docs/guides/guides/http-reference#query-strings

Return values

$this —

The current Request instance.

setRequest()

Completely override the request data for this request.


    public
                    setRequest(mixed $request) : $this

Parameters

$request : mixed: The request data.

Return values

$this —

The current Request instance.

setUrl()

Set the URL to send the request to, it can be fully qualified or relative to the Artillery script target URL.


    public
                    setUrl(string $url) : $this

Parameters

$url : string: The URL to send the request to.

Return values

$this —

The current Request instance.

Request extends RequestBase in package Application

Tags

Table of Contents

Properties

$request

Methods

addAfterResponse()

Parameters

Tags

Return values

addBeforeRequest()

Parameters

Tags

Return values

addCapture()

Parameters

Tags

Return values

addCaptures()

Parameters

Tags

Return values

addExpect()

Parameters

Tags

Return values

addExpects()

Parameters

Tags

Return values

addMatch()

Parameters

Tags

Return values

addMatches()

Parameters

Tags

Return values

set()

Parameters

Tags

Return values

setAuth()

Parameters

Tags

Return values

setBody()

Parameters

Tags

Return values

setCookie()

Parameters

Tags

Return values

setCookies()

Parameters

Tags

Return values

setFollowRedirect()

Parameters

Return values

setForm()

Parameters

Tags

Return values

setFormData()

Parameters

Tags

Return values

setFormDatas()

Parameters

Tags

Return values

setForms()

Parameters

Tags

Return values

setGzip()

Parameters

Return values

Request extends RequestBase
in package

Application