tessl/npm-nise

Fake XHR and server for testing JavaScript applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Timer-Integrated Server Mocking

Name: tessl/npm-nise
Author: tessl

Enhanced fake server that integrates with fake timers for testing time-dependent scenarios like request timeouts and delayed responses. This server automatically manages timer interactions, making it ideal for testing asynchronous operations with precise timing control.

Capabilities

Server Creation

Create a fake server with integrated timer support.

/**
 * @typedef {Object} FakeServerWithClock
 * @extends FakeServer
 * @property {Clock} [clock] - Reference to the fake timer clock
 * @property {number} [longestTimeout] - Longest timeout duration tracked for clock ticking
 * @property {boolean} [resetClock] - Flag indicating if the clock should be reset on cleanup
 */

/**
 * Create a fake server with integrated fake timer support
 * @param {ServerConfig} [config] - Optional configuration object (same as regular fake server)
 * @returns {FakeServerWithClock} FakeServerWithClock instance
 */
function create(config) {
  // Implementation
}

Usage Example:

const nise = require("nise");

const server = nise.fakeServerWithClock.create({
  autoRespond: true,
  autoRespondAfter: 1000 // 1 second delay
});

Timer Integration

The fake server with clock automatically integrates with SinonJS fake timers for precise timing control.

/**
 * Enhanced addRequest that manages fake timers
 * Automatically creates or uses existing fake timer clock
 * @param {XMLHttpRequest} xhr - The XMLHttpRequest to add
 * @returns {void}
 */
addRequest(xhr) {
  // Implementation
}

/**
 * Enhanced respond that advances fake timers
 * Automatically ticks the clock by the longest timeout duration
 * @returns {void}
 */
respond() {
  // Implementation
}

/**
 * Enhanced restore that cleans up fake timers
 * Uninstalls the clock if it was created by this server
 * @returns {void}
 */
restore() {
  // Implementation
}

Usage Example:

const sinon = require("sinon");
const nise = require("nise");

// Setup fake timers
const clock = sinon.useFakeTimers();

// Create server (will use existing clock)
const server = nise.fakeServerWithClock.create({
  autoRespond: true,
  autoRespondAfter: 5000
});

// Make request
fetch("/api/data");

// Manually advance time to trigger response
clock.tick(5000);

// Cleanup
server.restore();
clock.restore();

Automatic Clock Management

When no external fake timer clock is detected, the server automatically creates and manages its own clock.

/**
 * @typedef {Object} ClockLifecycle - Clock lifecycle properties
 * @property {Clock} clock - The fake timer clock instance
 * @property {number} longestTimeout - Tracks the longest timeout for proper time advancement
 * @property {boolean} resetClock - Flag to reset clock on server cleanup
 */

Usage Example:

const nise = require("nise");

// Server creates its own clock automatically
const server = nise.fakeServerWithClock.create({
  autoRespond: true,
  autoRespondAfter: 2000
});

// Make request - server handles timing automatically
fetch("/api/data");

// Server automatically advances its internal clock
server.respond(); // Processes request and advances time by 2000ms

// Cleanup automatically uninstalls the internal clock
server.restore();

Timeout Tracking

The server tracks timeout durations to ensure proper time advancement.

/**
 * @typedef {Object} TimeoutTracking - Enhanced setTimeout and setInterval tracking
 * @property {number} longestTimeout - Tracks the longest timeout duration seen
 */

Usage Example:

const server = nise.fakeServerWithClock.create();

// Configure delayed response
server.respondWith("GET", "/slow-api", [200, {}, "data"]);
server.autoRespondAfter = 10000; // 10 second delay

// Make request
fetch("/slow-api");

// Server tracks the 10 second timeout
console.log(server.longestTimeout); // 10000

// Respond advances clock by longest timeout
server.respond(); // Advances time by 10000ms

Integration with SinonJS

Using with Existing Fake Timers

When SinonJS fake timers are already installed, the server integrates seamlessly:

const sinon = require("sinon");
const nise = require("nise");

// Install fake timers first
const clock = sinon.useFakeTimers();

// Server detects and uses existing clock
const server = nise.fakeServerWithClock.create();

// Configure response with delay
server.autoRespond = true;
server.autoRespondAfter = 1000;

// Make request
fetch("/api/data");

// Manually control timing
clock.tick(1000); // Triggers the delayed response

// Cleanup
server.restore(); // Does not uninstall external clock
clock.restore();   // Manually restore external clock

Automatic Clock Creation

When no fake timers exist, the server creates its own:

const nise = require("nise");

// No existing fake timers
const server = nise.fakeServerWithClock.create();

// Server creates internal clock for timer integration
server.autoRespond = true;
server.autoRespondAfter = 500;

// Make request
fetch("/api/data");

// Server automatically manages timing
server.respond(); // Creates clock, advances time, then cleans up

// Final cleanup
server.restore(); // Uninstalls internal clock

Advanced Usage

Manual Clock Control

Access the internal clock for advanced timing scenarios:

const server = nise.fakeServerWithClock.create();

// Make async request
fetch("/api/data");

// Access internal clock
if (server.clock) {
  // Manually advance time
  server.clock.tick(1000);
  
  // Check current time
  console.log(Date.now()); // Shows fake time
}

Combining with Real Timers

Mix fake and real timers for complex scenarios:

const sinon = require("sinon");
const nise = require("nise");

// Fake only setTimeout, keep setInterval real
const clock = sinon.useFakeTimers({
  toFake: ['setTimeout']
});

const server = nise.fakeServerWithClock.create();

// setTimeout calls are faked and controlled
// setInterval calls use real time

Testing Timeout Scenarios

Test request timeout handling:

const server = nise.fakeServerWithClock.create();

// Don't configure any responses (requests will timeout)
server.autoRespond = false;

// Make request with timeout
const xhr = new XMLHttpRequest();
xhr.timeout = 5000;
xhr.open("GET", "/api/slow");
xhr.send();

// Advance time to trigger timeout
if (server.clock) {
  server.clock.tick(5000);
}

// Check that timeout occurred
console.log(xhr.readyState); // Should be DONE with timeout