Node.js QuickStart Guide

This guide will walk you through integrating Hypertest into your Node.js application. In about 10 minutes, you'll capture your first tests, run them against your code, and see HyperTest automatically catch a bug.

Prerequisites

• A working Node.js application.

• 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. Update Project Files

First, modify package.json to include the required dependencies and scripts.

1. Update package.json

Open your package.json and merge the following dependencies, devDependencies, and scripts.

{
  "name": "my-awesome-app",
  "version": "1.0.0",
  // ... other properties

  "dependencies": {
    "@hypertestco/node-sdk": "0.2.28-96",  // check the latest version from npm
    // ... your other dependencies
  },
  "devDependencies": {
    "@hypertestco/ht-cli": "0.2.28-96", // check the latest version from npm
    "nyc": "^17.1.0",
    // ... your other devDependencies
  },
  "scripts": {
    "start": "node index.js", // <-- IMPORTANT: Ensure this runs your app
    // ... your other scripts

    "start-app-with-nyc": "nyc --nycrc-path .ht-nycrc npm start",
    "ht:test": "htcli start-new-test --config-file-path .htConf.js",
    "ht:update-coverage": "htcli update-coverage --config-file-path .htConf.js --deduplicate",
    "ht:update-packages": "htcli update-ht-packages --package-manager npm --config-file-path ./.htConf.js"
  }
}

2. Install Packages

After saving the file, run this command in your terminal. It will read the updated package.json and install the new dependencies.

npm install
# or
yarn install
# or
pnpm install

3. Add Config Files in project root

Create two configuration files in your project's root directory.

1. .ht-nycrc (Tells nyc how to report coverage for HyperTest)

.ht-nycrc

{
    "exclude": ["node_modules", ".htConf.js", "coverage", ".nyc_output", "ht-coverage"],
    "reporter": ["json-summary", "html"],
    "report-dir": "ht-coverage",
    "cache": false
}

2. .htConf.js (Main configuration for the HyperTest CLI)

.htConf.js

const requestTypes = { HTTP: 'HTTP' };

module.exports = {
  // --- Required Configuration ---
  htBackendBaseUrl: "<URL of your HyperTest server>",
  serviceIdentifier: "<your-service-identifier-from-dashboard>",
  appStartCommand: process.platform === 'win32' ? 'npm.cmd' : 'npm',
  appStartCommandArgs: ["run", "start-app-with-nyc"],

  // --- Optional but Recommended ---
  httpCandidateUrl: "http://localhost:3000",
  appWorkingDirectory: __dirname,
  appStartTimeoutSec: 90,
  masterBranch: 'main', // Or 'master'
  requestTypesToTest: [requestTypes.HTTP],
};

2. Instrument Your Application

Now, add the HyperTest SDK to your app's main entry point (e.g., index.js, server.js, app.ts etc).

1. Initialize the SDK

Add this code to the very top of your entry file, before any other imports.

// process.env.APPLY_HT_OTEL_PATCH = 'yes'; // Set this env only if opentelemetry is already being used in your application.
process.env.HT_MODE = process.env.HT_MODE || 'RECORD'; // TODO: REMOVE THIS LINE BEFORE DEPLOYING TO PRODUCTION

import * as htSdk from '@hypertestco/node-sdk'; // for esm/ts
// const htSdk = require('@hypertestco/node-sdk'); // for commonJS
htSdk.initialize({
    apiKey: '<your-api-key>', // <-- Get from HyperTest dashboard
    serviceId: '<your-service-identifier-from-dashboard>', // <-- Get from dashboard
    serviceName: '<organizationName:service-name>', // e.g., "acme-corp:user-service"
    exporterUrl: '<hypertest-logger-url>', // <-- Provided by the HyperTest team
});

// No imports or require calls should be made before htSdk.initialize is called.
// Fight your instincts and your linters for this :)

2. Mark the App as Ready

Call htSdk.markAppAsReady() once your app is listening for requests.

// Example for an Express.js app
app.listen(3000, () => {
  console.log(`Listening for requests on http://localhost:3000`);
  // This tells HyperTest the app is ready for test replays.
  htSdk.markAppAsReady();
});

3. Capture & Establish Baseline

Let's generate your initial test suite and lock it in as the baseline.

1. Capture Tests

Start your app using the special nyc script.

npm run start-app-with-nyc

Now, use your app and make API calls (via Postman, cURL, etc.) to the endpoints you want to test. Check your HyperTest dashboard to see tests appear in real-time. When you're done, stop your application (Ctrl+C).

2. Establish Coverage Baseline

Run this command to save the current code coverage as the "golden" version.

npm run ht:update-coverage -- --skip-git-uncommitted-check

The update-coverage command is only supposed to be run on your master branch beacuse that establishes your current baseline of both reponses and code coverage The --skip-git-uncommitted-check flag is for debugging only which lets update-coverage command run on any branch After integration, you'll not be using the --skip-git-uncommitted-check flag

4. Catch Your First Bug!

This is the magic moment. Let's introduce a bug and watch HyperTest catch it.

1. Make a code change

In one of your API endpoints captured previously, introduce a small breaking change (e.g., change a response message, status code, or calculation).

2. Run the Test

Execute the main test command.

npm run ht:test

HyperTest will now start your app, replay the captured tests against your modified code, and compare the behavior against the baseline.

3. See the Results

The CLI will output a link to the test run on your HyperTest dashboard. Click it to see a detailed report of the regression you just introduced, complete with payload diffs and coverage changes.

Congratulations! You have successfully integrated HyperTest.