{"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,"search_vec":"'10.0.23':67 '18.2.0':112 'achiev':34 'actual':57 'allow':48 'appear':73 'asynchron':92 'base':97 'cadenc':71 'code':32 'consist':78 'control':39,89 'current':63 'date':96 'date-bas':95 'date.now':47 'design':11 'determinist':26 'develop':19 'differenti':84 'enabl':18 'ensur':99 'environ':90,109 'execut':51 'explicit':106 'frequent':76 'futur':24 'higher':114 'intern':40 'involv':53 'javascript':115 'javascript/typescript':8 'key':83 'lie':85 'logic':98 'manipul':13 'mock':37 'node.js':108 'oper':93 'packag':105 'patch':80 'primarili':77 'progress':55 'provid':87 'real':59 'real-tim':58 'releas':70,81 'reliabl':101 'requir':110 'scenario':52 'schedul':116 'sensit':31 'setinterv':45 'settimeout':44 'speed':103 'stabl':64 'system':15 'target':107 'test':9,27,49,100,117 'time':2,17,30,54,60 'time-sensit':29 'timer':41,118 'travel':3,21 'typescript':119 'util':4,10 'vehicl':1,5 'version':65,111 'wait':61 'without':56","created_at":"2026-04-20T18:44:48.005256+00:00","updated_at":"2026-04-20T18:44:48.005256+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/chrisguttandin/vehicles","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vehicles","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}