Artillery-plugin-expect is an official plugin for Artillery, a powerful open-source load and functional testing tool built with Node.js. This plugin extends Artillery's capabilities by adding support for declarative checks and assertions on HTTP requests directly within YAML test scripts. It enables users to perform functional or acceptance testing alongside performance testing, verifying response status codes, content types, headers, body properties (via JSONPath or JMESPath), and regex matches. The current stable version is 2.24.0, and its development and release cadence are now tightly integrated with the main Artillery project since its codebase was moved into the core repository in December 2022. This plugin is a key differentiator for Artillery, allowing comprehensive API testing (both load and functional) from a single, YAML-driven test definition, making it suitable for CI/CD pipelines to run post-deployment smoke tests.
npm install artillery-plugin-expectVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to install `artillery-plugin-expect` globally and configure a basic Artillery YAML script. It shows how to enable the plugin and add various HTTP expectations (status code, content type, body properties, equality, regex matching) to different request steps within a scenario, including using captured variables in assertions. It also illustrates how to use environments to switch between functional and load testing.
Ensure your scenarios use the HTTP engine. If you need custom logic with non-HTTP engines or within hooks, consider using custom JavaScript functions as steps in your flow to perform assertions manually or log data for later analysis.
Verify your `npm` or `yarn` installation strategy. If `artillery` is global, install plugins globally. If `artillery` is a local project dependency, install plugins as local `devDependencies`.
For reporting issues or contributing, refer to the main Artillery repository (artilleryio/artillery). Ensure you are using a recent version of Artillery that bundles this plugin's functionality or uses the latest compatible plugin package.
To ensure tests fail decisively on expectation errors, add `ensure` conditions to your `config` section, such as `maxErrorRate: 0` or specific `p99` thresholds, which will cause Artillery to exit with a non-zero code if conditions are not met. The plugin can also report failures as errors in the report via configuration, or you can use the `prettyError` output option.
Ensure the plugin is installed correctly. If Artillery is installed globally (`npm install -g artillery`), install the plugin globally too (`npm install -g artillery-plugin-expect`). If Artillery is a local project dependency, install the plugin as a local `devDependency` (`npm install --save-dev artillery-plugin-expect`). Also, check your YAML configuration for typos under `config.plugins`.
Review the details of the failed expectation in the Artillery output. Compare the `expected` value/condition with the `actual` value. Check your API's expected behavior, the test data, and the `expect` definition in your YAML script for any discrepancies. Use the `pretty` or `prettyError` output options for the plugin for more detailed debugging information.
Inspect the raw response body from your API to confirm the existence and exact path of the property you are trying to assert. Use `capture` with `json` or `jmespath` to debug what values are being extracted and ensure your JMESPath or JSONPath expressions are correct. Consider using `hasProperty` expectation first to check for existence before asserting on its value.