{"id":13384,"library":"jest-useragent-mock","title":"Jest User-Agent Mocking Utility","description":"jest-useragent-mock is a lightweight utility designed to facilitate the mocking of `navigator.userAgent` within Jest unit tests. It provides simple functions, `mockUserAgent` and `clear`, to set and reset the browser's user-agent string, making it easier to test browser-specific logic or user-agent dependent features. The current stable version is 0.1.1. Given its specific scope and low version, it operates on an infrequent release cadence, appearing to be in a maintenance state with no recent updates since its initial release. Its key differentiator is its singular focus on `navigator.userAgent` mocking, directly integrating with Jest's setup files for global application across test suites, distinguishing it from broader mocking libraries by offering a specialized, minimalist solution.","status":"maintenance","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/ariesjia/jest-useragent-mock","tags":["javascript","mock","jest","useragent","typescript"],"install":[{"cmd":"npm install jest-useragent-mock","lang":"bash","label":"npm"},{"cmd":"yarn add jest-useragent-mock","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest-useragent-mock","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a Jest test utility and requires Jest to run and function correctly. It relies on Jest's test environment and global setup capabilities.","package":"jest","optional":false}],"imports":[{"note":"The library primarily uses ES modules. While CommonJS might technically work, the recommended approach, especially with TypeScript, is ES module imports.","wrong":"const { mockUserAgent } = require('jest-useragent-mock');","symbol":"mockUserAgent","correct":"import { mockUserAgent } from 'jest-useragent-mock';"},{"note":"`clear` is a named export, not a default export. Ensure correct destructuring from the module.","wrong":"import clear from 'jest-useragent-mock';","symbol":"clear","correct":"import { clear } from 'jest-useragent-mock';"}],"quickstart":{"code":"import { clear, mockUserAgent } from 'jest-useragent-mock';\n\n// jest.config.js should include setupFiles: [\"jest-useragent-mock\"]\n\ndescribe('User-Agent Dependent Feature', () => {\n  afterEach(() => {\n    // It's crucial to clear the mock after each test to prevent side effects\n    // and ensure isolation between test cases.\n    clear();\n  });\n\n  it('should detect a Chrome user agent correctly', () => {\n    const chromeAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36';\n    mockUserAgent(chromeAgent);\n    expect(window.navigator.userAgent).toEqual(chromeAgent);\n    // Example of browser detection logic (simplistic)\n    const isChrome = window.navigator.userAgent.includes('Chrome') && !window.navigator.userAgent.includes('Edg');\n    expect(isChrome).toBe(true);\n  });\n\n  it('should detect a Firefox user agent correctly', () => {\n    const firefoxAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:99.0) Gecko/20100101 Firefox/99.0';\n    mockUserAgent(firefoxAgent);\n    expect(window.navigator.userAgent).toEqual(firefoxAgent);\n    const isFirefox = window.navigator.userAgent.includes('Firefox');\n    expect(isFirefox).toBe(true);\n  });\n});","lang":"typescript","description":"Demonstrates how to set up `jest-useragent-mock` with Jest's `setupFiles`, mock `navigator.userAgent` for specific tests, and ensure cleanup after each test."},"warnings":[{"fix":"Always include `afterEach(() => { clear(); });` in your test files or a shared setup script to reset the user agent mock.","message":"Failing to call `clear()` after each test can lead to global state pollution. Mocks will persist across tests, causing unpredictable behavior and flaky test results.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Jest configuration sets `testEnvironment: 'jsdom'` for test files that interact with browser globals like `window.navigator`.","message":"This package is explicitly designed for Jest and relies on a browser-like environment (e.g., `testEnvironment: 'jsdom'`). Using it in a Node.js-only Jest environment (`testEnvironment: 'node'`) will result in `window` or `navigator` being undefined.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Consider pinning the package version to avoid unexpected dependency resolution issues. For projects requiring active maintenance or advanced features, evaluate alternative, more actively developed mocking solutions or custom Jest setups.","message":"The package currently resides at a low version (0.1.1) and has seen no updates in several years. While functional for its stated purpose, the lack of active development means no new features, bug fixes, or compatibility updates for newer browser/Node.js versions or Jest major releases should be expected. Use with caution for long-term projects.","severity":"gotcha","affected_versions":"<=0.1.1"},{"fix":"Review your test suite and application code for other direct manipulations of `window.navigator.userAgent`. Isolate its usage to `jest-useragent-mock` within your Jest tests.","message":"The library works by modifying `window.navigator.userAgent` directly. If other parts of your test setup or application code also modify this global property, conflicts can occur. Ensure `jest-useragent-mock` is the sole modifier in your test environment for this specific property.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Configure Jest to use a browser-like environment by adding `testEnvironment: 'jsdom'` to your `jest.config.js` or within the test file's docblock.","cause":"Jest is running tests in a Node.js environment (`testEnvironment: 'node'`) which lacks browser globals like `window`.","error":"ReferenceError: window is not defined"},{"fix":"Set `testEnvironment: 'jsdom'` in your Jest configuration.","cause":"`navigator` or `window.navigator` is undefined, typically due to the same reason as 'window is not defined'.","error":"TypeError: Cannot read properties of undefined (reading 'userAgent')"},{"fix":"Ensure `jest-useragent-mock` is correctly listed in `setupFiles` in `jest.config.js` and that `clear()` is called in an `afterEach` hook.","cause":"The mock set by `mockUserAgent` is not being applied, or a previous mock was not cleared, leading to an incorrect `userAgent` value.","error":"Expected: 'test-agent' Received: 'default-agent' (or an unexpected user agent string)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}