npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hyperactive

v2.3.0

Published

Creates mocha tests for all hypermedia of your API

Downloads

13

Readme

hyperactive

Small utility used to actively test your API by crawling the hypermedia links

Logo

Build Status Dependency Status devDependency Status

npm install

How does it work?

hyperactive crawls your API responses, and creates mocha tests for each unique link it finds. Simply pass in some basic config and it will do the rest.

var hyperactive = require('hyperactive');

describe("My API", function() {
  it("should be discoverable", function() {
    hyperactive.crawl({
      url: "http://myApiEndpoint.com/route",
      options: {
        headers: {
          Accept: "application/json"
        }
      }
    });
  })
})

Hyperactive will then recursively crawl your API, and make sure it can make a GET request to every URL. Any 4xx or 5xx status code while crawling makes the corresponding test fail, and the usual Mocha summary gets printed at the end:

1) http://my-api.com/route/that/fails
   Bad status 404

 70 passing (2613ms)
  1 failing

Note: hyperactive needs to run as part of a mocha test suite. If you want to run it in a different context, just make sure it and describe are defined in the global scope.

More options

- How do I configure extra HTTP options?

For SSL and basicAuth, just add the following to the config:

var hyperactive = require('hyperactive');

describe("My API", function() {
  it("should be discoverable", function() {
    hyperactive.crawl({
      url: "http://myApiEndpoint.com/route",
      options: {
        headers: {
          Accept: "application/json"
        },
        auth : {
          user: "myUsername",
          pass: "myPassword"
        },
        secureProtocol : "SSLv3_client_method",
        strictSSL : false
      }
    });
  })
})

Note: hyperactive uses unirest to send requests. The options hash can contain any valid Request option from unirest.

- How does it find hypermedia links?

By default, hyperactive looks for links according to the HAL spec:

{
  "resource": {
    "name": "my resource",
    "id": 1,
    "_links": {
      "link1": {
        "href": "http://myApiEndpoint.com/route1"
      },
      "link2": {
        "href": "http://myApiEndpoint.com/route2"
      }
    }
  }
}

If you have a different format for links, you can pass your own link finder. For example, if your API returns the following:

{
  "resource": {
    "name": "my resource",
    "id": 1
  },
  "links": [
    "http://myApiEndpoint.com/route1",
    "http://myApiEndpoint.com/route2"
  ]
}

then you can call hyperactive with:

function getLinks(responseBody) {
  return responseBody.links;
}

hyperactive.crawl({
  url: "http://myApiEndpoint.com/route",
  options: {
    headers: {
      Accept: "application/json"
    },
  },
  getLinks: getLinks
});

The getLinks function receives a Unirest response and should return an array of links for that response. It's up to you to get these links recursively if you have links nested at several levels inside the response.

- How do I validate the responses?

By default hyperactive just checks that each response returns a HTTP 200 (i.e. res.ok === true). You can also pass custom validation function. For example, if you have the following response:

{
  "success": true,
  "resource": {
    "name": "my resource",
    "id": 1,
    "_links": {
      "link1": {
        "href": "http://myApiEndpoint.com/route1"
      },
      "link2": {
        "href": "http://myApiEndpoint.com/route2"
      }
    }
  }
}

Then you can validate it with:

function validate(url, responseBody) {
  if(url.match(/some-url/)) {
    return responseBody.success;
  }
  return true;
}

hyperactive.crawl({
  url: "http://myApiEndpoint.com/route",
  options: {
    headers: {
      Accept: "application/json"
    },
  },
  validate: validate
});

- Will it crawl EVERYTHING?

By default, yes. If that's taking too long, you can also crawl a percentage of all links:

hyperactive.crawl({
  url: "http://myApiEndpoint.com/route",
  options: {
    headers: {
      Accept: "application/json"
    },
  },
  samplePercentage: 75
});

- Will it crawl link with URI template ?

Yes, you have to specify the values to be used in the URI template

hyperactive.crawl({
  url: "http://myApiEndpoint.com/route",
  templateValues: {
    jurisdiction: 'NSW'
  }
});

Even the start url could be a template

hyperactive.crawl({
  url: "http://myApiEndpoint.com/route?jurisdiction={jurisdiction}",
  templateValues: {
    jurisdiction: 'NSW'
  }
});

Can I configure failure thresholds?

By default, hyperactive fails any URL that responds with 4xx or 5xx. To handle intermittent issues, you can pass a custom recover function, which can make a test pass despite the errors. Note that this doesn't handle any errors returned from your custom validate function, this is just for recovering from HTTP errors.

For example, you can setup a threshold for 400 errors using:

var failures = 0;

hyperactive.crawl({
  recover: function(res) {
    return (res.statusCode === 400 && ++failure < 10);
  }
});

How can I contribute?

The usual process:

npm install
npm test

And if everything is passing, submit a pull request :)