{"id":15016,"library":"vehicles","title":"Vehicles Time Travel Utility","description":"Vehicles is a JavaScript/TypeScript testing utility designed to manipulate the system's time, enabling developers to 'travel into the future' for deterministic testing of time-sensitive code. It achieves this by mocking and controlling internal timers, such as `setTimeout`, `setInterval`, and `Date.now()`, allowing tests to execute scenarios involving time progression without actual real-time waits. The current stable version is 10.0.23, with a release cadence that appears to be frequent, primarily consisting of patch releases. Its key differentiator lies in providing a controlled environment for asynchronous operations and date-based logic, ensuring test reliability and speed. The package explicitly targets Node.js environments, requiring version 18.2.0 or higher.","status":"active","version":"10.0.23","language":"javascript","source_language":"en","source_url":"https://github.com/chrisguttandin/vehicles","tags":["javascript","scheduler","testing","timer","typescript"],"install":[{"cmd":"npm install vehicles","lang":"bash","label":"npm"},{"cmd":"yarn add vehicles","lang":"bash","label":"yarn"},{"cmd":"pnpm add vehicles","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Vehicles is primarily an ESM module; CommonJS 'require' syntax may lead to runtime errors, especially with default imports or when the bundler doesn't handle interop correctly. Use named imports for specific utility functions.","wrong":"const { travel } = require('vehicles');","symbol":"travel","correct":"import { travel } from 'vehicles';"},{"note":"The 'reset' function is a named export from the main package, not a subpath. It's crucial for cleaning up time mocks between tests.","wrong":"import reset from 'vehicles/reset';","symbol":"reset","correct":"import { reset } from 'vehicles';"},{"note":"When importing types for use in TypeScript, ensure you use 'import type' to avoid including runtime code, which can prevent tree-shaking and lead to unexpected behavior.","wrong":"import { MockedDate } from 'vehicles';","symbol":"MockedDate","correct":"import type { MockedDate } from 'vehicles';"}],"quickstart":{"code":"import { travel, reset } from 'vehicles';\n\ndescribe('Time-sensitive feature', () => {\n  // Store original Date to restore after all tests\n  const originalDate = global.Date;\n\n  beforeEach(() => {\n    // Reset time mocks before each test to ensure isolation\n    reset();\n  });\n\n  afterAll(() => {\n    // Restore global Date object after all tests in the suite\n    global.Date = originalDate;\n  });\n\n  it('should trigger an event after a specific delay', async () => {\n    let eventTriggered = false;\n    setTimeout(() => {\n      eventTriggered = true;\n    }, 10000); // 10 seconds\n\n    // Initial state check\n    expect(eventTriggered).toBe(false);\n\n    // Travel 5 seconds into the future\n    await travel(5000);\n    expect(eventTriggered).toBe(false); // Should still be false\n\n    // Travel another 5 seconds (total 10) to trigger the event\n    await travel(5000);\n    expect(eventTriggered).toBe(true);\n  });\n\n  it('should mock current date correctly', async () => {\n    const initialDate = new Date();\n    await travel(60 * 60 * 1000); // Travel 1 hour into the future\n    const afterTravelDate = new Date();\n    expect(afterTravelDate.getTime()).toBe(initialDate.getTime() + 60 * 60 * 1000);\n  });\n});","lang":"typescript","description":"Demonstrates how to use `vehicles` to mock and advance timers for testing asynchronous, time-dependent logic and validating mocked date objects."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18.2.0 or newer. Consider using a version manager like `nvm` to manage multiple Node.js versions.","message":"The package requires Node.js version 18.2.0 or higher. Using it with older Node.js versions will result in runtime errors related to unsupported syntax or APIs, specifically ESM features.","severity":"breaking","affected_versions":"<18.2.0"},{"fix":"Ensure your project is configured for ES Modules (e.g., `\"type\": \"module\"` in `package.json`) or use dynamic `import()` for ESM modules within CommonJS contexts where necessary.","message":"Vehicles primarily operates as an ES Module (ESM). Attempting to import it using CommonJS `require()` syntax in a pure CommonJS project might lead to errors like 'ERR_REQUIRE_ESM' or incorrect module resolution, even with bundlers, unless explicit interop is configured.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always include `reset()` in a `beforeEach` or `afterEach` hook within your test suite to ensure a clean state for time mocks before each test runs.","message":"Forgetting to call `reset()` between tests can lead to test pollution, where time mocks from a previous test affect subsequent tests, causing flaky or incorrect results.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Check the import statement. Ensure you are importing the correct named function (e.g., `travel`) and not trying to call the module itself, for example: `import { travel } from 'vehicles';`.","cause":"Attempting to call the top-level 'vehicles' module as a function, or incorrectly destructuring a named export when a default export was expected (or vice-versa).","error":"TypeError: vehicles is not a function"},{"fix":"Update your project to use ES Modules (by adding `\"type\": \"module\"` to `package.json`) and use `import` statements, or switch to dynamic `import('vehicles')` if mixing CJS and ESM.","cause":"Trying to `require()` the `vehicles` package, which is an ES Module, from a CommonJS context.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure your test runner (e.g., Jest, Mocha) is configured to run in a Node.js environment or has access to Node.js global timers. Verify that no other library or setup is inadvertently removing global timer functions before `vehicles` initializes.","cause":"This error typically indicates that the `vehicles` library, or another part of your test setup, is attempting to mock or interact with timers in an environment where the global `setTimeout` (or other timer functions) is not available or has been unexpectedly removed. This might occur if a test runner's environment is not correctly configured for Node.js globals.","error":"ReferenceError: setTimeout is not defined"}],"ecosystem":"npm"}