2. Tutorials
  3. hapi — Test Route Handlers by Injecting Requests

hapi — Test Route Handlers by Injecting Requests

One of the reasons we’re passionate about hapi is its easiness of testing. The framework has a built-in server.inject method that simulates an incoming HTTP request.

A server.inject call won’t create a socket connection. You’re not relying to the network stack to run tests in your app. That means, testing your app locally is delightful, because you don’t need a complete end-to-end setup consuming a ton of ports due to hapi server instances!

If you haven’t seen the related tutorials on getting started with testing in hapi using lab and code and assertions with code, give them a shot.

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Zero-Downtime Deployments Using PM2

How to Inject Requests to hapi

Let’s start with a practical example. You should be familiar with the skeleton of a test in hapi. If not, head over to the getting started with testing in hapi tutorial and get a grasp on it.

Injecting requests into a hapi server is great for testing. You don’t need to create a dedicated hapi server and run it on a port on your local or testing machine. There’s no socket connection required to inject a request into hapi and receive an response. The server.inject() method makes it possible.

The server.inject method accepts to types of parameters:

  • the request URL as a string value
  • an options object containing request details

Let’s look at both ways.

The Quick Way to Inject Requests

To quickly inject a request to a hapi server, provide a request path directly to server.inject('/request-path').

// … imports (lab, code), assignments, export lab script, etc. :)

describe('inject requests with server.inject,', () => {  
  it('quickly injects a request', async () => {
    const server = new Hapi.Server()

    // wait for the response and the request to finish
    const response = await server.inject('/request-path')
  })
})

In the code snippet above, hapi performs a GET request on the /request-path URL path. To run more complex requests, use an options object which is described in the upcoming subsection.

Inject Requests Based on an Options Object

Have a look at the following code snippet that outlines a basic test. The test creates a new hapi server and directly injects a GET request to /.

We expect this request to pass the request lifecycle and hapi to respond.

'use strict'

// … imports (lab, code), assignments, export lab script, etc. :)

describe('inject requests with server.inject,', () => {  
  it('injects a request to a hapi server without a route', async () => {
    const server = new Hapi.Server()

    // these must match the route you want to test
    const injectOptions = {
      method: 'GET',
      url: '/'
    }

    // wait for the response and the request to finish
    const response = await server.inject(injectOptions)

    // alright, set your expectations :)
    expect(response.statusCode).to.equal(404)
  })
})

You can copy and paste this test to your environment and run it. It’ll pass, because the newly created hapi server instance doesn’t serve this route. That’s why it responds with Not Found 404.

Notice that the injected request to a hapi server bases on the provided options. Let’s have a look at available options that you can assign with a request injection.

Options For server.inject

Anytime you’re passing an options object to a method, you don’t necessarily know the available fields. In such cases head over to the hapi API documentation and look out for the related method. In this situation, you’re heading for the section of server.inject(options).

Scrolling through the available options you’ll notice that there’s a single required option: url. Everything else has a default or null value which works in the majority of use cases.

For example, the method field defaults to GET and we could remove the method: 'GET' in the example above. That comes with knowledge depth and not every developer might know this default value. Be explicit when possible.

Have a look at the linked API section in hapi’s docs for server.inject. It allows you to inject request headers, params and payload. You can also pass credentials to bypass authentication or adjust the plugin states for the route to call. We’ll look at these scenarios in upcoming tutorials 😃

Inject a Request to a Route Handler

The previous example is at a bare minimum. Let’s look at a more complex example and add a route with a request handler to the hapi server. That gets us closer to a real situation where you’re adding your routes to a hapi server and testing the handlers by injecting requests.

The difference in this example is that you’re writing the route handler within the test itself. That’s probably not the case in your hapi app 😉

03-inject-requests.js

const Lab = require('lab')  
const Code = require('code')  
const Path = require('path')  
const Hapi = require('hapi')

// Test files must require the lab module, and export a test script
const lab = (exports.lab = Lab.script())

// shortcuts from lab
const { describe, it } = lab

// shortcuts from code
const expect = Code.expect

describe('inject requests with server.inject,', () => {

  it('inject a request', async () => {
    const server = new Hapi.Server()
    server.route({
      method: 'GET',
      path: '/',
      handler: () => {
        return {
          name: 'Marcus',
          isDeveloper: true,
          isHapiPassionate: 'YEEEEAHHH'
        }
      }
    })

    // these must match the route you want to test
    const injectOptions = {
      method: 'GET',
      url: '/'
    }

    // wait for the response and the request to finish
    const response = await server.inject(injectOptions)

    // alright, set your expectations :)
    expect(response.statusCode).to.equal(200)

    // shortcut to payload
    const payload = JSON.parse(response.payload)
    expect(payload.name).to.equal('Marcus')

    // of course you can assign more “expect” statements
  })
})

The route registration with server.route tells the server instance to listen for requests at GET / and respond with a JavaScript object consisting of name, isDeveloper and isHapiPassionate fields.

When testing this specific route, the options for server.inject need to match the route’s options. Pass the same HTTP method (GET) and path (/) to server.inject(injectOptions) as defined in server.route(routeOptions).

Ultimately, wait for the response and set your expectations. Pun intended 😅

This kind of testing with a route handler in the test itself is a good way to test your hapi plugins that extend the request lifecycle.

If you’re writing a hapi plugin that extends, e.g. onPreHandler, and you want to test it, register that plugin to the hapi server instance and let a handler return a value that you’d assert as a result. This way you can make sure your plugin works correctly.

Find the Test Files in the Futureflix Starter Kit

There’s a dedicated test file with the examples from this tutorial in the Futureflix Starter Kit’s test directory.

Look out for the file called 03-inject-requests.js. There you find this tutorial’s code snippets in a single file.

Outlook

Hopefully you can see the benefits of injecting requests in hapi. It allows you to run an integration test of route handlers where a request passes the request lifecycle as any actual request would do.

Have a look at all the options that server.inject(options) accepts to customize the payload, headers, params, credentials, and behavior of the injected request. We’ll walk through the details on injecting data with requests in the next tutorial 😉

We’re happy to hear your thoughts and appreciate your comment. Please don’t hesitate to use the comment form below. If Twitter is more your thing, find us @futurestud_io. Let us know what you think!

Enjoy coding & make it rock!

Mentioned Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous