# mock-vir

> The heroic mock for anything.

Latest version **2.0.2** (published 2026-07-01) · (MIT OR CC0-1.0) license · 0 weekly downloads

## Install

```sh
npm install mock-vir
pnpm add mock-vir
yarn add mock-vir
bun add mock-vir
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.2 |
| Published | 2026-07-01 |
| First published | 2022-10-31 |
| Weekly downloads | 0 |
| License | (MIT OR CC0-1.0) |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 18.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | electrovir |
| Maintainers | electrovir |
| Keywords | mock, vir, testing |

## Links

- npm: https://www.npmjs.com/package/mock-vir
- Repository: https://github.com/electrovir/mock-vir
- Issues: https://github.com/electrovir/mock-vir/issues
- npm.io page: https://npm.io/package/mock-vir

## Dependencies (1)

- [@augment-vir/assert](https://npm.io/package/@augment-vir/assert.md) ^32.0.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads
- [aws-elasticsearch-connector](https://npm.io/package/aws-elasticsearch-connector.md) — 37.4K weekly downloads

## Recent versions

- 2.0.2 (latest) — 2026-07-01
- 2.0.1 — 2025-06-25
- 2.0.0 — 2024-11-17
- 1.0.0 — 2024-02-19
- 0.1.3 — 2023-11-20
- 0.1.2 — 2023-10-02
- 0.1.1 — 2023-05-31
- 0.1.0 — 2023-02-14
- 0.0.6 — 2023-02-14
- 0.0.5 — 2022-12-07
- 0.0.4 — 2022-11-30
- 0.0.3 — 2022-11-30
- 0.0.2 — 2022-10-31
- 0.0.1 — 2022-10-31
- 0.0.0 — 2022-10-31

## README

# mock-vir

The heroic mock for anything.

# Usage

```bash
npm i -D mock-vir
```

## Creating a mock

Create a simple mock with `createMockVir`. Make sure to pass in the type generic for what you are mocking. After creating the mock, you can access all properties on the mock as if it were the originally given type.

<!-- example-link: src/readme-examples/creating-a-mock.example.ts -->

```TypeScript
import {createMockVir} from '..//index.js';

type ThingToMock = {
    nestedObject: {
        exampleChild: string;
    };
};

const myMock = createMockVir<ThingToMock>();

console.info(myMock.nestedObject.exampleChild);
```

## Nested mocks

Nested objects will always be accessible from the mock, even without defining them all before run-time. (This is possible by using the JS built-in [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy).)

<!-- example-link: src/readme-examples/accessing-nested-objects.example.ts -->

```TypeScript
import {createMockVir} from 'mock-vir';

type ThingToMock = {
    exampleChild: string;
};

const myMock = createMockVir<ThingToMock>();

console.info(myMock.exampleChild);
```

## Setting a mock's value

To set a mock's value (so it can be accessed in tests), just set the value directly on the mock.

<!-- example-link: src/readme-examples/setting-mock-value.example.ts -->

```TypeScript
import {createMockVir} from '..//index.js';

type ThingToMock = {
    nestedObject: {
        exampleChild: string;
    };
};

const myMock = createMockVir<ThingToMock>();

myMock.nestedObject.exampleChild = 'whatever';

// this will log "whatever"
console.info(myMock.nestedObject.exampleChild);
```

## Setting a function's return value

This is where things get interesting! You can set the return value for a mock's nested function by using the `keyForSettingMockReturnValue` symbol.

Note: when accessing this symbol, you must `as` cast your mock to use `WithMockVir` so that TypeScript knows this is indeed the mock wrapper of the base type, not the base type itself.

<!-- example-link: src/readme-examples/setting-return-value.example.ts -->

```TypeScript
import {createMockVir, keyForSettingMockReturnValue, type WithMockVir} from '..//index.js';

type ThingToMock = {
    nestedObject: {
        exampleChild: () => string;
    };
};

const myMock = createMockVir<ThingToMock>() as WithMockVir<ThingToMock>;

myMock.nestedObject.exampleChild[keyForSettingMockReturnValue] = 'whatever';

// this will log "whatever"
console.info(myMock.nestedObject.exampleChild());
```

## Accessing arguments from a function call after the fact

After running a test, you can access the arguments that a function in the mock was called with.

Note: when accessing this symbol, you must `as` cast your mock to use `WithMockVir` so that TypeScript knows this is indeed the mock wrapper of the base type, not the base type itself.

<!-- example-link: src/readme-examples/accessing-called-args.example.ts -->

```TypeScript
import {
    createMockVir,
    keyForReadingLastCalledArgs,
    keyForSettingMockReturnValue,
    type WithMockVir,
} from 'mock-vir';

type ThingToMock = {
    nestedObject: {
        exampleChild: (dummyInput: number) => string;
    };
};

const myMock = createMockVir<ThingToMock>() as WithMockVir<ThingToMock>;

myMock.nestedObject.exampleChild[keyForSettingMockReturnValue] = 'whatever';

// call the function
// this will happen in the source code that you are testing
myMock.nestedObject.exampleChild(42);

// this will log 42
console.info(myMock.nestedObject.exampleChild[keyForReadingLastCalledArgs]);
```

---
_Source: https://npm.io/package/mock-vir · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._