Node.js SDK

0. Prerequisites

1. A working Node.js application.

2. Access to your HyperTest dashboard to get your API Key and Service ID.

Before adding HyperTest code, confirm your application starts correctly on your machine. This ensures that any future issues are related to the integration, not your base application. Start your app and hit a few requests to confirm this before proceeding further.

1. Installing node-SDK package

npm install @hypertestco/node-sdk-v3 nyc --save-exact 

2. Initializing sdk

2.1 Create ht-init file

ht-init.js or ht-init.ts

// process.env.APPLY_HT_OTEL_PATCH = 'yes'; // Set this env only if opentelemetry is already being used in your application.

import * as htSdk from '@hypertestco/node-sdk-v3'; // for esm/ts
// const htSdk = require('@hypertestco/node-sdk-v3'); // for commonJS

// hypertest runs only if process.env.HT_MODE is set to 'RECORD'.
// It is safe to run this code as-is in production because HT_MODE wont be set to RECORD there
htSdk.initialize({
    apiKey: '<your-api-key>',
    serviceId: '<your-service-identifier-from-dashboard>',
    serviceName: '<organizationName:service-name>',
    exporterUrl: '<hypertest-logger-url>'
});

2.3 import ht-init file at the top in entrypoint

Entrypoint is the first js/ts file that gets executed. It might be index.ts, app.ts, src/main.ts etc. check your package.json

This needs to happen as early one line no 1 of your entrypoint. Make sure no require/import call is made before these lines. (dotenv is allowed)

// import this on absolute top inside (line number 1) of your JS app entrypont (app.js , main.ts, index.js etc)
import './ht-init'; // for esm/ts
// OR
require('./ht-init'); // for commonJS

// ... rest of imports
// ... rest of file

3. Add ht-start command in package.json

Identify if you're running a commonJS app or an ESM app. CommonJS is legacy and the default option in older nodejs versions For a CommonJS app.

package.json

{
  "scripts": {
    "start": "node src/index.js", // <-- assuming this starts your app
    
    // add this for a CommonJS app
    "ht-start": "HT_MODE=RECORD nyc node src/index.js"
    // add this for nestjs apps
    "ht-start": "HT_MODE=RECORD nyc nest start" 

  }
}

For an ESM app, you'll need to add a build step

package.json

{
  "scripts": {
    "start": "node src/index.js", // <-- assuming this starts your app

    // add this for an ESM app
    "ht-instrument": "nyc instrument src instrumented_src",
    "ht-run-instrumented-app":"HT_MODE=RECORD nyc node --loader=@hypertestco/node-sdk-v3/hooks.mjs instrumented_src/index.js",
    "ht-start": "npm run ht-instrument && npm run ht-run-instrumented-app"
  }
}

4. Verifying traffic is captured

# start your application with hypertest
npm run ht-start

you should see these logs at the start of your application

Hypertest started in mode: RECORD
Hypertest SDK version: <version>

Start sending http requests on your app running with hypertest sdk.

You should start seeing requests under All requests section on the dashboard