PuppyJS | Docs π
PuppyJS is a great HTTP and WebSocket testing and mocking tool, but currently only supports sending web socket messages on an interval to test a front end client. I needed something that could receive socket messages and then optionally send subsequent events back to the client application.
The presence of an action property determines whether the socket is configured as an emitter or a receiver. See extended samples below for setting up action/reaction socket messaging in the puppy.ws.js configuration file.
PuppyJS is a framework agnostic E2E (end-to-end) testing and mocking tool for front end developers. Puppy depends on Jest for tests and Puppeteer for the testing environment so if you know these tools then you already know 80% of Puppy.
Puppy also lets you mock HTTP APIs and web socket events so you can develop your application until the backend is ready as well as run your E2E tests against the same mock API and socket events you used for development.
npm install puppyjs --save-dev
npm install puppyjs --global
puppy --help
puppy serve
puppy test
Below you can find a sample directory structure. The important thing to notice are the puppy.api.js
, puppy.ws.js
and puppy.config.js
and that they are at the root level of the directory.
.
|
βββ puppy.config.js <optional>
βββ puppy.api.js <optional>
βββ puppy.ws.js <optional>
|
βββ package.json
|
βββ dist
| βββ background.jpg
| βββ index.html
| βββ fonts
|
βββ tests
βββ users.pup.js
βββ notifications.pup.js
Sample:
module.exports = {
'/api/users': {
'GET': {
headers: {
'Authorization': 'Bearer some-token'
},
status: 200,
body: 'hello its a GET'
}
}
}
Sample periodic emitter:
module.exports = {
'notification': {
delay: 1000,
interval: 1000,
message: [
{seen: false, createdAt: Date.now(), text: 'I am a notification'}
]
}
}
Simple socket receive:
module.exports = {
'action': {
delay: 1000,
message: 'get-server-list',
action: () => {}
}
}
The presence of an action property identifies this as a receiver and will delay 1 second to perform the get-server-list message. The function is empty, so no action will take place once this message has been received.
Simple action/reaction socket receive:
module.exports = {
'simpleReaction': {
delay: 1000,
message: 'get-server-list',
action: () => {
return 'initialize-server-list';
}
}
}
This configuration will wait for the message get-server-list then, after 1 second, it will return a simple message back to the client socket with the contents of initialize-server-list for processing.
Action/reaction with payload via sockets:
module.exports = {
'payloadReaction': {
delay: 1000,
message: 'get-server-list',
action: (data) => {
return {
message: 'load-server-list',
servers: [ 'Server abc1', 'Server abc2', 'Server abc3' ],
pattern: data.pattern,
param: data.param2
};
}
}
}
This configuration will wait for the message get-server-list then, after 1 second, it will return an object message back to the client. Notice that this also recieves and includes a payload from the original event. See section below for client message format for sending socket payloads.
Multiple Action/reaction via sockets:
If you need to have multiple reactions from a single client message, you can simply create multiple definitions using the same message value.
module.exports = {
'simpleReaction': {
delay: 1000,
message: 'get-server-list',
action: () => {
return 'initialize-server-list';
}
},
'payloadReaction': {
delay: 1000,
message: 'get-server-list',
action: (data) => {
return {
message: 'load-server-list',
servers: [ 'Server abc1', 'Server abc2', 'Server abc3' ],
pattern: data.pattern,
param: data.param2
};
}
}
}
The above configuration will send two messages to the client initialize-server-list, followed by load-server-list for each get-server-list request.
Sample:
module.exports = {
port: 1337
}
Underneath, Puppy uses Jest for asserting and Puppeteer for executing actions in the browser. Please head to their documentation if you are not familiar.
In the example below it assumes a file index.html
inside src
folder and a file with any name but ends with .pup.js
which will hold the test.
describe('test', () => {
let page
it('check that puppy works', async () => {
page = await puppy.newPage('https://localhost:1337/src/index.html') // page instance is a puppeteer page instance
... your code
expect(...) // Jest
})
}
To run this use the command
puppy test
You can use the same puppy.api.js
file that you configure above for development purpose. Run puppy serve
and you can now make a GET
request to /api/users
and get a reply back as set in the puppy.api.js
file.
When using socket receiver actions, there are two recognized formats sending the client messages as a payload:
When a socket reciever is set up in the configuration file, a request from the client can be a simple string with the name of the event to trigger. For example:
get-server-list
This payload will execute the action setup in the configuration file with a message property of get-server-list.
In order to transmit a payload to the receiver action configuration, define the message payload to be a stringified JSON object using the format:
{
"event": "get-server-list",
"payload": { ... }
}
The event property will match the action(s) in the configuration file and pass in the payload as a parameter to the action. The payload can be any type (object, array, string) and will be preserved as such in the action function.
The following message submitted by the client:
{
"event": "get-server-list",
"payload": {
"pattern": "abc*",
"param2": "some text value"
}
}
can be received and used by the action function:
action: (data) => {
return {
message: 'load-server-list',
servers: [ 'Server abc1', 'Server abc2', 'Server abc3' ],
pattern: data.pattern,
param: data.param2
};