https://github.com/lensesio/cypress-websocket-testing
Test WebSocket connections with Cypress
https://github.com/lensesio/cypress-websocket-testing
cypress testing websocket
Last synced: 4 months ago
JSON representation
Test WebSocket connections with Cypress
- Host: GitHub
- URL: https://github.com/lensesio/cypress-websocket-testing
- Owner: lensesio
- License: apache-2.0
- Created: 2019-11-21T16:07:27.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-07-12T04:16:27.000Z (almost 3 years ago)
- Last Synced: 2025-06-11T16:53:05.206Z (about 1 year ago)
- Topics: cypress, testing, websocket
- Language: TypeScript
- Homepage:
- Size: 1.03 MB
- Stars: 83
- Watchers: 10
- Forks: 11
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# cypress-websocket-testing
Test your WebSocket endpoints using [Cypress](https://docs.cypress.io/).
[](https://travis-ci.com/Lensesio/cypress-websocket-testing)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/semantic-release/semantic-release)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/ellerbrock/typescript-badges/)
## Table of Contents
- [Background](#Background)
- [Installation](#Installation)
- [Usage](#Usage)
- [JavaScript](#JavaScript)
- [TypeScript](#TypeScript)
- [Arguments](#Arguments)
- [Running the examples](#Running-the-examples)
- [PRs](#prs)
- [TODO](#TODO)
- [License](#license)
## Background
Cypress comes out of the box with a great set of tools that allow both UI and API integration tests to be written. Unfortunately the `cy.request()` command is limited to REST endpoints only, so this library is here to help with those cases when WebSockets need to be called/tested as part of more complex integration/E2E tests.
## Installation
```bash
npm i -D @lensesio/cypress-websocket-testing
# or
yarn add -D @lensesio/cypress-websocket-testing
```
You also need to add `rxjs` to the project.
```bash
npm i -D rxjs
```
## Usage
### JavaScript
`@lensesio/cypress-websocket-testing` extends Cypress' `cy` command.
Add this line to your project's `cypress/support/commands.js`:
```
import { addStreamCommands } from '@lensesio/cypress-websocket-testing';
addStreamCommands();
```
Then, in your test, you can use both commands that come with this lib. cy.stream and cy.streamRequest.
```javascript
// For common cases:
cy.streamRequest(config, options).then(results => {
expect(results).to.not.be.undefined;
})
// When in need of a bit more flexibility
cy.stream(config).then(subject => {
subject
.pipe(
takeUntil(timer(1000)),
reduce((acc , val) => acc.concat([val]), [])
)
.subscribe({
next: (results) => {
expect(results).to.not.be.undefined;
},
error: (err) => {},
complete: done
});
});
```
### TypeScript
As the library is written in Typescript, you can pass the type of the message to the command and to the config/options object. ( make sure that you already configured your Cypress tests to work [with TS](https://github.com/bahmutov/add-typescript-to-cypress) )
First, add `@lensesio/cypress-websocket-testing` to the `cypress/tsconfig.json` file
```
{
"compilerOptions": {
"types": [
"cypress",
"@lensesio/cypress-websocket-testing"
]
}
}
```
Then to use in TypeScript tests:
```typescript
// For full set of config values, check rxjs documentation
const config: WebSocketSubjectConfig = {
url: "ws://localhost:8080/"
};
let options: Partial>;
cy.streamRequest(config, options).then((results?: IMessage[]) => {
expect(results).to.not.be.undefined;
})
cy.stream(config).then(subject => {
subject
.pipe(
takeUntil(timer(1000)),
reduce((acc: IMessage[], val: IMessage) => acc.concat([val]), [])
)
.subscribe({
next: (results?: IMessage[]) => {
expect(results).to.not.be.undefined;
},
error: (err: any) => {},
complete: done
});
});
```
Note:
There are some type conflicts when extending/adding operators to cy.stream() in tests directly. (due to issues with Cypress including an old rxjs version as a dependency). Best way is to extend cy.stream() by building a custom command with it and use that instead.
## Arguments
- config
A [WebSocketSubjectConfig](https://rxjs-dev.firebaseapp.com/api/webSocket/WebSocketSubjectConfig) object. See official docs for more information. Is passed as is to the underlying webSocket subject.
- options:StreamRequestOptions (only for streamRequest command. Although optional, at least the takeWhileFn should be set)
Usage `cy.streamRequest(config, options)`.
| Option | Default | Description |
| -------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `streamTimeout` | `defaultCommandTimeout` | Time to wait for the stream to complete. (if is greater than Cypress defaultCommandTimeout, you need to use the cy.wrap as a workaround. Investigating alternative ways) |
| `retryDelay` | `4000` | How long to way until a new connection attempt is made. |
| `retryAttempts` | `5` | How many times to retry the connection before completing. |
| `startUpMessage` | `any` | A message to be sent on connection open. |
| `takeWhileFn` | `()=>false` | Function that will tell the stream when to close. If not set, it will close on the first message received in order to avoid having an open connection. |
| `retryUntilFn` | `()=>true` | Function that will tell the stream how to check the results, and retry if the result is false. |
## Running the examples
In order to try this project locally, you need to `npm install` in both the root and the examples/ folder.
After, build the library using `npm run build` in the root folder, then go to examples/ , start the websocket server `npm start` and cypress using `npm run test:local`.
## PRs
PRs are welcome. Be sure to add
- Tests
- Reason for the PR
When committing, remember to use `npm run commit`, in order to start commitizen.
## TODO
- [] Find a fix for the cy.wrap workaround.
- [] Improve error handling.
- [] Add more examples for cy.stream command.
## LICENSE
[Apache 2.0](LICENSE.md)