README

Artillery.io is a modern, powerful & easy-to-use performance testing toolkit.

ArtilleryPhp is a library to write and maintain Artillery scripts in PHP8.

• Documentation: bundeling.github.io/ArtilleryPhp
• Examples: ArtilleryPhp-examples

Documentation contains:

• Full explanation for each class and method.
• Example code for each class and most methods.
• Links to every section of the Artillery reference docs.

Table of Contents

• Installation
• Usage
• Artillery Class
• Scenario Class
• Request Class

Installation

You can install the library via Composer:

composer require bundeling/artilleryphp

This library requires the symfony/yaml package to render its internal arrays to a YAML format.

Usage

This example is available at examples/artilleryphp-usage.

Step 1: Create a new Artillery instance

You can use Artillery::new($target) to get a new instance, and use the fluent interface to set config values:

use ArtilleryPhp\Artillery;

$artillery = Artillery::new('http://localhost:3000')
    ->addPhase(['duration' => 60, 'arrivalRate' => 5, 'rampTo' => 20], 'Warm up')
    ->addPhase(['duration' => 60, 'arrivalRate' => 20], 'Sustain')
    ->setPlugin('expect')
    ->setEnvironment('live', ['target' => 'https://www.example.com']);

You can also create one from a full or partial array representation:

$artillery = Artillery::fromArray([
    'config' => [
        'target' => 'http://localhost:3000',
        'phases' => [
            ['duration' => 60, 'arrivalRate' => 5, 'rampTo' => 20, 'name' => 'Warm up'],
            ['duration' => 60, 'arrivalRate' => 20, 'name' => 'Sustain'],
        ],
        'plugins' => [
            // To produce an empty object as "{  }", use stdClass.
            // This is automatic when using setPlugin(s), setEngine(s) and setJson(s).
            'expect' => new stdClass(),
        ],
        'environments' => [
            'live' => ['target' => 'https://www.example.com']
        ]
    ]
]);

And from an existing YAML file, or other Artillery instance:

! Warning: The methods fromYaml and merge are not very well supported right now; fromYaml mostly works with outputs from this library; and merge will do nothing if second level keys are already defined (e.g. trying to merge a second environment).

$config = Artillery::fromYaml(__DIR__ . '/default-config.yml');
$environments = Artillery::fromYaml(__DIR__ . '/default-environments.yml');

// New instance from the config, and merging in environments from another file:
$artillery = Artillery::from($config)->merge($environments);

Step 2: Define the flow of your scenario and add it to the Artillery instance:

// Create some requests:
$loginRequest = Artillery::request('get', '/login')
    ->addCapture('token', 'json', '$.token')
    ->addExpect('statusCode', 200)
    ->addExpect('contentType', 'json')
    ->addExpect('hasProperty', 'token');
    
$inboxRequest = Artillery::request('get', '/inbox')
    ->setQueryString('token', '{{ token }}')
    ->addExpect('statusCode', 200);

// Create a flow with the requests, and a 500ms delay between:
$flow = Artillery::scenario()
    ->addRequest($loginRequest)
    ->addThink(0.5)
    ->addRequest($inboxRequest);

// Let's loop the flow 10 times:
$scenario = Artillery::scenario()->addLoop($flow, 10);

// Add the scenario to the Artillery instance:
$artillery->addScenario($scenario);

Tips:

Plural versions exist to take multiple entries of raw array representations:

$loginRequest = Artillery::request('post', '/login')
    ->setQueryStrings([
        'username' => '{{ username }}',
        'password' => '{{ password }}'])
    ->addCaptures([
        ['json' => '$.token', 'as' => 'token'],
        ['json' => '$.id', 'as' => 'id']]);

Take note of the difference between the set and add differentiation, and;
Refer to the Artillery reference docs for raw representation specs.

Step 3: Export to YAML:

// Without argument will build the YAML as the same name as the php file:
$artillery->build();

// Maybe even run the script right away (assumes `npm install -g artillery`):
$artillery->run();

This will produce the following readme-example.yml file:

config:
  target: 'http://localhost:3000'
  phases:
    - duration: 60
      arrivalRate: 5
      rampTo: 20
      name: 'Warm up'
    - duration: 60
      arrivalRate: 20
      name: Sustain
  plugins:
    expect: {  }
scenarios:
  - flow:
      - loop:
          - get:
              url: /login
              capture:
                - json: $.token
                  as: token
              expect:
                - statusCode: 200
                - contentType: json
                - hasProperty: token
          - think: 0.5
          - get:
              url: /inbox
              qs:
                token: '{{ token }}'
              expect:
                - statusCode: 200
        count: 10

Tips:

For a very basic script, you can also add Requests (single or array) directly to the Artillery instance to create a new Scenario out of it:

$artillery = Artillery::new()
    ->addScenario(Artillery::request('get', 'http://www.google.com'));

Notes

Current implementation builds up an internal array representation. This means that there's limited or no support for operations like getting a Scenario instance from a specific index or unsetting a property. For now think in terms of composition, and look forward to v2.

Artillery Class

The Artillery class has all the methods related to the config section of the Artillery script, along with adding scenarios.

Docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Artillery

For custom config settings, there is a set(key: string, value: mixed) function available.

Target:

If a target is set, it will be used as the base Url for all the requests in the script.

You can either pass the base Url in the constructor or use the setTarget method on the Artillery instance. You can also skip this step entirely and provide fully qualified Urls in each Request.

// Base URL in the Scenario with relateve path in the request:
$artillery = Artillery::new('http://localhost:3000')
    ->addScenario(Artillery::request('get', '/home'));

// Without target, and fully qualified URL in Request:
$artillery = Artillery::new()
    ->addScenario(Artillery::request('get', 'http://localhost:3000/home'));
    
// Setting the target when initializing from another source:
$file = __DIR__ . '/default-config.yml';
$default = Artillery::fromYaml($file)
    ->setTarget('http://www.example.com');

$artillery = Artillery::from($default)
    ->setTarget('http://localhost:3000');

Environments:

Environments can be specified with overrides for the config, such as the target URL and phases.

You can either use the config of another Artillery instance, or as an array of config values:

$local = Artillery::new('http://localhost:8080')
    ->addPhase(['duration' => 30, 'arrivalRate' => 1, 'rampTo' => 10])
    ->setHttpTimeout(60);

$production = Artillery::new('https://example.com')
    ->addPhase(['duration' => 300, 'arrivalRate' => 10, 'rampTo' => 100])
    ->setHttpTimeout(30);

$artillery = Artillery::new()
    ->setEnvironment('staging', ['target' => 'https://staging.example.com'])
    ->setEnvironment('production', $production)
    ->setEnvironment('local', $local);

Static factory helpers: use these to get a new instance and immediately call methods on them:

• Artillery: new([targetUrl: null|string = null]): Artillery
• Scenario: scenario([name: null|string = null]): Scenario
• Request: request([method: null|string = null], [url: null|string = null]): Request
• WsRequest: wsRequest([method: null|string = null], [request: mixed = null]): WsRequest
• AnyRequest: anyRequest([method: null|string = null], [request: mixed = null]): AnyRequest

$artillery = Artillery::new($targetUrl)
    ->addPhase(['duration' => 60, 'arrivalRate' => 10]);
    
$request = Artillery::request('get', '/login')
    ->addCapture('token', 'json', '$.token');
    
$scenario = Artillery::scenario('Logging in')->addRequest($request);

Scenario-related methods:

You can add a fully built scenario, or pass a single Request or array of Requests, and a Scenario will be made from it.

See the Scenario Class for more details.

• addScenario(scenario: array|RequestInterface|RequestInterface[]|Scenario, [options: mixed[]|null = null])
  • Add a Scenario to the scenarios section of the Artillery script.
• setAfter(after: array|RequestInterface|RequestInterface[]|Scenario)
  • Set a Scenario to run after a Scenario from the scenarios section is complete.
• setBefore(before: array|RequestInterface|RequestInterface[]|Scenario)
  • Adds a Scenario to run before any given Scenario from the scenarios section.

Processor & function hooks:

A scenario's flow, and requests, can have JavaScript function hooks that can read and modify context such as variables.

Here's a very demonstrative example from examples/generating-vu-tokens:

// This scenario will run once before any main scenarios/virtual users; here we're using a js function 
// from a processor to generate a variable available in all future scenarios and their virtual users:
$before = Artillery::scenario()->addFunction('generateSharedToken');

// One of the main scenarios, which has access to the shared token,
// and here we're generating a token unique to every main scenario that executed.
$scenario = Artillery::scenario()
    ->addFunction('generateVUToken')
    ->addLog('VU id: {{ $uuid }}')
    ->addLog('    shared token is: {{ sharedToken }}')
    ->addLog('    VU-specific token is: {{ vuToken }}')
    ->addRequest(
        Artillery::request('get', '/')
            ->setHeaders([
                'x-auth-one' => '{{ sharedToken }}',
                'x-auth-two' => '{{ vuToken }}'
            ]));

$artillery = Artillery::new('http://www.artillery.io')
    ->setProcessor('./helpers.js')
    ->setBefore($before)
    ->addScenario($scenario);

With ./helpers.js as:

module.exports = {
  generateSharedToken,
  generateVUToken
};

function generateSharedToken(context, events, done) {
  context.vars.sharedToken = `shared-token-${Date.now()}`;
  return done();
}

function generateVUToken(context, events, done) {
  context.vars.vuToken = `vu-token-${Date.now()}`;
  return done();
}

See also Artillery.io docs for necessary function signatures.

Config settings:

Please refer to the docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Artillery#methods

• addEnsureCondition(expression: string, [strict: bool|null = null])
• addEnsureConditions(thresholds: array[])
• addEnsureThreshold(metricName: string, value: int)
• addEnsureThresholds(thresholds: int[][])
• setEngine(name: string, [options: array|null = null])
• setEngines(engines: array[]|string[])
• setEnvironment(name: string, config: array|Artillery)
• setEnvironments(environments: array[]|Artillery[])
• addPayload(path: string, fields: array, [options: bool[]|string[] = [...]])
• addPayloads(payloads: bool[][]|string[][])
• addPhase(phase: array, [name: null|string = null])
• addPhases(phases: array[])
• setPlugin(name: string, [options: array|null = null])
• setPlugins(plugins: array)
• setVariable(name: string, value: mixed)
• setVariables(variables: mixed[])
• setHttp(key: string, value: bool|int|mixed)
• setHttps(options: bool[]|int[])
• setHttpTimeout(timeout: int)
• setHttpMaxSockets(maxSockets: int)
• setHttpExtendedMetrics([extendedMetrics: bool = true])
• setProcessor(path: string)
• setTarget(url: string)
• setTls(rejectUnauthorized: bool)
• setWs(wsOptions: array)

Rendering and Loading:

• build([file: null|string = null]): Artillery Builds the script and save it as a YAML file.
• toYaml(): string Renders the script to a Yaml string.
• from(artillery: Artillery): Artillery New Artillery instance from given Artillery instance.
• fromArray(script: array): Artillery New Artillery instance from given array data.
• fromYaml(file: string): Artillery New Artillery instance from given Yaml file.
• toArray(): array Gets the array representation of the current Artillery instance.
• run([reportFile: null|string = null], [debug: null|string = null]): Artillery Runs the built script (or builds and runs-), and save the report to a file with a timestamp.

Scenario Class

The Scenario class includes all the methods related to a scenario and its flow.

Docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Scenario

// Imagine we have an already defined Scenario as $defaultScenario
$scenario = Artillery::scenario()  
    ->setName('Request, pause 2 seconds, then default flow.')
    ->addRequest(Artillery::request('GET', '/'))  
    ->addThink(2)  
    ->addFlow($defaultScenario);

Methods:

Docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Scenario#methods

Custom Scenario settings:

• set(key: string, value: mixed)

Adding to the flow from another scenario into this scenario:

• addFlow(scenario: Scenario)

Misc:

• setName(name: string) Used for metric reports.
• setWeight(weight: int) Default: 1. Determines the probability that this scenario will be picked compared to other scenarios in the Artillery script.

If not set, the engine defaults to HTTP requests. To create a WebSocket scenario, you need to specify this scenario's engine as 'ws' and only use instances of the WsRequest class, available at Artillery::wsRequest().

• setEngine(engine: string)

Scenario-level JavaScript function hook, from the Js file defined in setProcessor in the Artillery instance:

• addAfterScenario(function: array|string|string[])
• addBeforeScenario(function: array|string|string[])

Similarly, for requests, there are scenario level hooks for before and after:

• addAfterResponse(function: array|string|string[])
• addBeforeRequest(function: array|string|string[])

See Artillery.io docs for more details on js function hooks.

Flow methods:

• addRequest(request: RequestInterface)
• addRequests(requests: RequestInterface[])
• addLoop(loop: array|RequestInterface|RequestInterface[]|Scenario|Scenario[], [count: int|null = null], [over: null|string = null], [whileTrue: null|string = null])
• addLog(message: string, [ifTrue: null|string = null])
• addThink(duration: float, [ifTrue: null|string = null])
• addFunction(function: array|string|string[], [ifTrue: null|string = null])

Request Class

Docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Request

The Request class has all the methods related to HTTP requests along with some shared methods inherited from a RequestBase class.

$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!']);

For WebSocket there is a crude implementation of the WsRequest class available at Artillery::wsRequest().

$stringScenario = Artillery::scenario('Sending a string')
    ->setEngine('ws')
    ->addRequest(Artillery::wsRequest('send', 'Artillery'));

For custom requests AnyRequest is meant to be used anonymously with these functions:

• set(key: string, value: mixed)
• setMethod(method: string)
• setRequest(request: mixed)

$emitAndValidateResponse = Artillery::scenario('Emit and validate response')
    ->setEngine('socketio')
    ->addRequest(
        Artillery::anyRequest('emit')
            ->set('channel', 'echo')
            ->set('data', 'Hello from Artillery')
            ->set('response', ['channel' => 'echoResponse', 'data' => 'Hello from Artillery']));

Methods:

Please refer to the docs: https://bundeling.github.io/ArtilleryPhp/classes/ArtilleryPhp-Request#methods

• addAfterResponse(function: array|string|string[])
• addBeforeRequest(function: array|string|string[])
• setAuth(user: string, pass: string)
• setBody(body: mixed)
• setCookie(name: string, value: string)
• setCookies(cookies: string[])
• setFollowRedirect([followRedirect: bool = true])
• setForm(key: string, value: mixed)
• setForms(form: array)
• setFormDatas(formData: array)
• setFormData(key: string, value: mixed)
• setGzip([gzip: bool = true])
• setHeader(key: string, value: string)
• setHeaders(headers: string[])
• setIfTrue(expression: string)
• setJson([key: null|string = null], [value: mixed = null])
• setJsons(jsons: mixed[])
• setMethod(method: string)
• setQueryString(key: string, value: mixed)
• setQueryStrings(qs: array)
• setUrl(url: string)

Inherited:

• set(key: string, data: mixed)
• setMethod(method: string)
• setRequest(request: mixed)
• addCapture(as: string, type: string, expression: string, [strict: bool = true], [attr: null|string = null], [index: int|null|string = null])
• addCaptures(captures: int[][]|string[][])
• addExpect(type: string, value: mixed, [equals: mixed = null])
• addExpects(expects: mixed[][])
• addMatch(type: string, expression: string, value: mixed, [strict: bool = true], [attr: null|string = null], [index: int|null|string = null])
• addMatches(matches: mixed[][])