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-68", // check the latest version from npm
// ... your other dependencies
},
"devDependencies": {
"@hypertestco/ht-cli": "0.2.28-68", // 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",
"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)
{
"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)
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-uncommited-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-uncommited-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-uncommited-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.
Last updated