Skip to content

gatekeeper leverages ngrok & node's events module to capture webhooks and helps in integrating assertions for your webhooks with your integration / e2e tests

License

Notifications You must be signed in to change notification settings

kartik1998/gatekeeper

Repository files navigation

G𝕒te𝕜ee𝕡er

Build Status

Capture your webhooks in your integration / end to end tests and write assertions for them. Normally to test webhooks webhook.site or some similar platform is used, however you can't automate and write assertions over the data recieved through these webhooks.
P.S postman also offers a solution link but I found the workflow a little time consuming. Gatekeeper solves this problem via node's event emitter module and makes writing tests for webhooks seamless. Sample gatekeeper webhook tests with chai, mocha and supertest

Installation

npm install @kartikkhk/gatekeeper

AppModule

  • If you're writing your integration tests with (chai, mocha, supertest etc..) then you just need to import AppModule, start the webhook server and wait for webhooks via AppModules utility methods

Usage

  • sample implementation: link
  • Please note that AppModule is singleton in nature and the webhook's base url has to be updated by the user. refer sample below
const { AppModule } = require('@kartikkhk/gatekeeper');
const webhook = AppModule.Instance(); // webhook server by default runs on port 3009 (this is configurable, configurations listed below)

describe('user integration tests', function () {
  this.timeout(100000);
  before(async () => {
    await webhook.startWebhookServer();
    const localUrl = await webhook.getLocalUrl();
    process.env.WEBHOOK_URL = localUrl; // or whatever your key for webhook url is like process.env.WEBHOOK_BASE_URL
  });

  it('user test description', async () => {
    // synchronous api response assertions
    const response = await request(app).get('/endpoint');
    expect(response.status).to.equal(200);
    // synchronous api response assertions

    // assertions for webhooks recieved
    const webhookResponse = await webhook.wait(); // default timeout of 1 minute
    /* can also be used like await webhook.wait(60 * 2000) //timeout of 2 minutes */
    expect(webhookResponse.body).to.deep.equal(<what you expect webhook body to be>);
    expect(webhookResponse.headers).to.deep.equal(<what you expect webhook headers to be>);
  });
});
  • Sample webhook.wait() result:
{
  "method": "POST",
  "body": {
    "msg": "webhook"
  },
  "headers": {
    "Content-Type": "application/json"
  },
  "query": {},
  "originalUrl": "/webhook/xyz"
}

AppModule Configuration

  • Sample usage:
const webhook = AppModule.Instance({ port: 5002, logWebhooksToConsole: true, disableNgrok: true... });
Option Type Description
port number (default=3009) port on which webhook server runs on
logWebhooksToConsole boolean (default=false) Logs all recieved webhooks to console
expectedResponse { status: number, body: any } (default= {status: 200, body: { msg: 'webhook recieved' }}) The response that you want your webhook server to give your application
disableNgrok boolean (default=false) Disables ngrok url creation for webhook server
ngrokOpts view options here (default={ addr: port }) ngrok options
debug boolean (default=false) Writes gatekeeper debug and info logs to console (use only while debugging)

Method Description
createWebhookTestId creates a unique uuid (webhookTestId) and attaches it to recieving webhooks headers. It's useful because it's possible that a webhook.wait()s timeout can exceed and the webhook is then recieved in the next test. Sample usage: link
getWebhookTestId returns current webhookTestId
startWebhookServer starts webhook server (if the server is already running then it just logs that the server is already running)
setExpectedResponse you can use this to set the response that your application will get from webhook server, usage: webhook.setExpectedResponse(body, status)
getExpectedResponse gets the expectedResponse
wait Each recieved webhook is queued (if it isn't collected from wait method). i.e. when a webhook is recieved an event is emitted and if that event isn't consumed then the webhook is queued. Hence when the wait method is called it either collects webhook data from a queue or waits for a webhook event to fire. Hence each webhook is processed serially
getLocalUrl gets the webhook server's local url eg. http://localhost:3009
getNgrokUrl gets the webhook server's ngrok url eg. http://a985-122-161-75-46.ngrok.io

E2EModule

  • E2EModule is slightly different from AppModule. I recommend you use it when you want to test code running on an external server. (This means that you can use E2EModule for testing webhooks for an application written in any language since you're basically just making an api call and writing assertions over the response ;) )

Usage

  • sample implementation: link
  • Please note that E2EModule is singleton in nature and the webhook's base url has to be updated by the user. (This means you might have to ssh into your external server and replace your webhook url with the ngrok url. If you're sending the webhook url in your requests then you can ignore this step) refer sample below
const { E2EModule } = require('@kartikkhk/gatekeeper');
const webhook = E2EModule.Instance();
describe('E2EModule user tests', function () {
  this.timeout(100000);
  before(async () => {
    await webhook.startWebhookServer();
    const ngrokUrl = await webhook.getNgrokUrl();
    console.log(ngrokUrl); // Place a debugger breakpoint here, copy the ngrokUrl and change the webhook url in your server, you can skip this step if you are sending the webhook url in your requests
  });

  after(() => {
    process.exit();
  });

  it('user test description', async () => {
    // synchronous api response assertions
    const response = await axios.get('http://<server-ip>:<port>/endpoint');
    expect(response.status).to.equal(200);
    // synchronous api response assertions

    // assertions for webhooks recieved
    const webhookResponse = await webhook.wait(); // default timeout of 1 minute
    /* can also be used like await webhook.wait(60 * 2000) //timeout of 2 minutes */
    expect(webhookResponse.body).to.deep.equal(<what you expect webhook body to be>);
    expect(webhookResponse.headers).to.deep.equal(<what you expect webhook headers to be>);
  });
});

E2EModule Configuration

  • Sample usage:
const webhook = E2EModule.Instance({ port: 5002, logWebhooksToConsole: true, disableNgrok: true... });
Option Type Description
port number (default=3009) port on which webhook server runs on
logWebhooksToConsole boolean (default=false) Logs all recieved webhooks to console
expectedResponse { status: number, body: any } (default= {status: 200, body: { msg: 'webhook recieved' }}) The response that you want your webhook server to give your application
ngrokOpts view options here (default={ addr: port }) ngrok options
debug boolean (default=false) Writes gatekeeper debug and info logs to console (use only while debugging)

Method Description
startWebhookServer starts webhook server (if the server is already running then it just logs that the server is already running)
setExpectedResponse you can use this to set the response that your application will get from webhook server, usage: webhook.setExpectedResponse(body, status)
getExpectedResponse gets the expectedResponse
wait Each recieved webhook is queued (if it isn't collected from wait method). i.e. when a webhook is recieved an event is emitted and if that event isn't consumed then the webhook is queued. Hence when the wait method is called it either collects webhook data from a queue or waits for a webhook event to fire. Hence each webhook is processed serially
getLocalUrl gets the webhook server's local url eg. http://localhost:3009
getNgrokUrl gets the webhook server's ngrok url eg. http://a985-122-161-75-46.ngrok.io

Gatekeeper Workflow

gatekeeper workflow

LICENSE

MIT

About

gatekeeper leverages ngrok & node's events module to capture webhooks and helps in integrating assertions for your webhooks with your integration / e2e tests

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

No packages published