# @serenity-js/rest

> Serenity/JS Screenplay Pattern library for interacting with REST and other HTTP-based services, supporting comprehensive API testing and blended testing scenarios

Latest version **3.48.0** (published 2026-09-15) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @serenity-js/rest
pnpm add @serenity-js/rest
yarn add @serenity-js/rest
bun add @serenity-js/rest
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.48.0 |
| Published | 2026-09-15 |
| First published | 2017-12-21 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^22.22.2 \|\| ^24.15.0 |
| Dependencies | 7 |
| Unpacked size | 514.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 617 |
| Author | Jan Molak |
| Maintainers | jan-molak |
| Keywords | automation, integration, serenity, serenity-js, screenplay, screenplay-pattern, http, rest, axios, tdd, bdd, test, testing |

## Links

- npm: https://www.npmjs.com/package/@serenity-js/rest
- Repository: https://github.com/serenity-js/serenity-js
- Homepage: https://serenity-js.org
- Issues: https://github.com/serenity-js/serenity-js/issues
- Funding: https://github.com/sponsors/serenity-js
- npm.io page: https://npm.io/package/@serenity-js/rest

## Dependencies (7)

- [axios](https://npm.io/package/axios.md) 1.20.0
- [lru-cache](https://npm.io/package/lru-cache.md) 11.5.2
- [agent-base](https://npm.io/package/agent-base.md) 7.1.4
- [tiny-types](https://npm.io/package/tiny-types.md) 2.0.5
- [http-proxy-agent](https://npm.io/package/http-proxy-agent.md) 7.0.2
- [@serenity-js/core](https://npm.io/package/@serenity-js/core.md) 3.48.0
- [https-proxy-agent](https://npm.io/package/https-proxy-agent.md) 7.0.6

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 3.48.0 (latest) — 2026-09-15
- 2.0.1-alpha.131 (next) — 2020-02-03
- 3.47.2 — 2026-09-10
- 3.47.0 — 2026-09-09
- 3.46.1 — 2026-09-04
- 3.46.0 — 2026-08-30
- 3.45.9 — 2026-08-20
- 3.45.8 — 2026-08-20
- 3.45.7 — 2026-08-18
- 3.45.6 — 2026-08-15
- 3.45.5 — 2026-08-14
- 3.45.4 — 2026-08-13
- 3.45.3 — 2026-08-13
- 3.45.2 — 2026-08-13
- 3.45.1 — 2026-08-13
- … 420 more at https://npm.io/package/@serenity-js/rest/versions

## README

# Serenity/JS REST

[![NPM Version](https://badge.fury.io/js/%40serenity-js%2Frest.svg)](https://badge.fury.io/js/%40serenity-js%2Frest)
[![Build Status](https://github.com/serenity-js/serenity-js/actions/workflows/main.yaml/badge.svg?branch=main)](https://github.com/serenity-js/serenity-js/actions)
[![Maintainability](https://qlty.sh/gh/serenity-js/projects/serenity-js/maintainability.svg)](https://qlty.sh/gh/serenity-js/projects/serenity-js)
[![Code Coverage](https://qlty.sh/gh/serenity-js/projects/serenity-js/coverage.svg)](https://qlty.sh/gh/serenity-js/projects/serenity-js)
[![Contributors](https://img.shields.io/github/contributors/serenity-js/serenity-js.svg)](https://github.com/serenity-js/serenity-js/graphs/contributors)
[![Known Vulnerabilities](https://snyk.io/test/npm/@serenity-js/rest/badge.svg)](https://snyk.io/test/npm/@serenity-js/rest)
[![GitHub stars](https://img.shields.io/github/stars/serenity-js/serenity-js?style=flat)](https://github.com/serenity-js/serenity-js)

[![Follow Serenity/JS on LinkedIn](https://img.shields.io/badge/Follow-Serenity%2FJS%20-0077B5?logo=linkedin)](https://www.linkedin.com/company/serenity-js)
[![Watch Serenity/JS on YouTube](https://img.shields.io/badge/Watch-@serenity--js-E62117?logo=youtube)](https://www.youtube.com/@serenity-js)
[![Join Serenity/JS Community Chat](https://img.shields.io/badge/Chat-Serenity%2FJS%20Community-FBD30B?logo=matrix)](https://matrix.to/#/#serenity-js:gitter.im)
[![Support Serenity/JS on GitHub](https://img.shields.io/badge/Support-@serenity--js-703EC8?logo=github)](https://github.com/sponsors/serenity-js)

[`@serenity-js/rest`](https://serenity-js.org/api/rest/) enables actors to perform HTTP requests and validate responses in [Screenplay](https://serenity-js.org/handbook/design/screenplay-pattern/) tests.

## Features

- Integrates Serenity/JS with Axios providing standardised [Screenplay REST API](https://serenity-js.org/api/rest/)
- Compatible with all the [Serenity/JS modules](https://serenity-js.org/api/) and [supported test runners](https://serenity-js.org/handbook/test-runners/)

## Installation

```sh
npm install --save-dev @serenity-js/core @serenity-js/rest @serenity-js/assertions axios
```

See the [Serenity/JS Installation Guide](https://serenity-js.org/handbook/installation/).

## Quick Start

```typescript
import { actorCalled } from '@serenity-js/core'
import { CallAnApi, DeleteRequest, GetRequest, LastResponse, PostRequest, Send } from '@serenity-js/rest'
import { Ensure, equals, startsWith } from '@serenity-js/assertions'

const actor = actorCalled('Apisit').whoCan(CallAnApi.at('https://myapp.com/api'))

await actor.attemptsTo(
    // no users present in the system
    Send.a(GetRequest.to('/users')),
    Ensure.that(LastResponse.status(), equals(200)),
    Ensure.that(LastResponse.body(), equals([])),

    // create a new test user account
    Send.a(PostRequest.to('/users').with({
        login: 'tester',
        password: 'P@ssword1',
    }),
    Ensure.that(LastResponse.status(), equals(201)),
    Ensure.that(LastResponse.header('Location'), startsWith('/users')),

    // delete the test user account
    Send.a(DeleteRequest.to(LastResponse.header('Location'))),
    Ensure.that(LastResponse.status(), equals(200)),
)
```

Explore practical examples and in-depth explanations in the [Serenity/JS Handbook](https://serenity-js.org/handbook/).

## Documentation

- [API Reference](https://serenity-js.org/api/)
- [Screenplay Pattern Guide](https://serenity-js.org/handbook/design/screenplay-pattern/)
- [Serenity/JS Project Templates](https://serenity-js.org/handbook/project-templates/)
- [Tutorial: First Web Scenario](https://serenity-js.org/handbook/tutorials/your-first-web-scenario/)
- [Tutorial: First API Scenario](https://serenity-js.org/handbook/tutorials/your-first-api-scenario/)

## Contributing

Contributions of all kinds are welcome! Get started with the [Contributing Guide](https://serenity-js.org/community/contributing/).

## Community

- [Community Chat](https://matrix.to/#/#serenity-js:gitter.im)
- [Discussions Forum](https://github.com/orgs/serenity-js/discussions)
    - Visit the [💡How to... ?](https://github.com/orgs/serenity-js/discussions/categories/how-to) section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ⭐️ [Serenity/JS on GitHub](https://github.com/serenity-js/serenity-js) to help others discover the framework!

## License

The Serenity/JS code base is licensed under the [Apache-2.0](https://opensource.org/license/apache-2-0) license,
while its documentation and the [Serenity/JS Handbook](https://serenity-js.org/handbook/) are licensed under the [Creative Commons BY-NC-SA 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/).

See the [Serenity/JS License](https://serenity-js.org/legal/license/).

## Support

Support ongoing development through [GitHub Sponsors](https://github.com/sponsors/serenity-js). Sponsors gain access to [Serenity/JS Playbooks](https://github.com/serenity-js/playbooks)
and priority help in the [Discussions Forum](https://github.com/orgs/serenity-js/discussions).

For corporate sponsorship or commercial support, please contact [Jan Molak](https://www.linkedin.com/in/janmolak/).

[![GitHub Sponsors](https://img.shields.io/badge/Support%20@serenity%2FJS-703EC8?style=for-the-badge&logo=github&logoColor=white)](https://github.com/sponsors/serenity-js)

---
_Source: https://npm.io/package/@serenity-js/rest · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._