{"id":15017404,"url":"https://github.com/morganstanley/ts-mocking-bird","last_synced_at":"2025-04-07T16:18:38.639Z","repository":{"id":39971149,"uuid":"252729719","full_name":"morganstanley/ts-mocking-bird","owner":"morganstanley","description":"A fully type safe mocking, call verification and import replacement library for jasmine and jest","archived":false,"fork":false,"pushed_at":"2025-03-25T20:04:36.000Z","size":10055,"stargazers_count":21,"open_issues_count":2,"forks_count":5,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-31T14:13:26.629Z","etag":null,"topics":["jasmine","jest","testing","typescript"],"latest_commit_sha":null,"homepage":"http://opensource.morganstanley.com/ts-mocking-bird/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/morganstanley.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-03T12:43:11.000Z","updated_at":"2025-03-25T20:03:10.000Z","dependencies_parsed_at":"2023-02-15T08:17:07.438Z","dependency_job_id":"256c15cd-7f5b-428f-9e80-7e0a792460d1","html_url":"https://github.com/morganstanley/ts-mocking-bird","commit_stats":{"total_commits":227,"total_committers":7,"mean_commits":32.42857142857143,"dds":0.3215859030837004,"last_synced_commit":"3c0bf7eabcacccff12a270aeb38a7501af86bda6"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morganstanley%2Fts-mocking-bird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morganstanley%2Fts-mocking-bird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morganstanley%2Fts-mocking-bird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morganstanley%2Fts-mocking-bird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/morganstanley","download_url":"https://codeload.github.com/morganstanley/ts-mocking-bird/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247685628,"owners_count":20979085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jasmine","jest","testing","typescript"],"created_at":"2024-09-24T19:50:24.799Z","updated_at":"2025-04-07T16:18:38.613Z","avatar_url":"https://github.com/morganstanley.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @morgan-stanley/ts-mocking-bird\n![Lifecycle Active](https://badgen.net/badge/Lifecycle/Active/green)\n![npm](https://img.shields.io/npm/v/@morgan-stanley/ts-mocking-bird)\n[![Build Status](https://github.com/morganstanley/ts-mocking-bird/actions/workflows/build.yml/badge.svg)](https://github.com/Roaders/ts-mocking-bird/actions/workflows/build.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/morganstanley/ts-mocking-bird/badge.svg)](https://snyk.io/test/github/morganstanley/ts-mocking-bird})\n![NPM](https://img.shields.io/npm/l/@morgan-stanley/ts-mocking-bird)\n![NPM](https://img.shields.io/badge/types-TypeScript-blue)\n\n\n\n\u003e A fully type safe mocking, call verification and import replacement library that works with jasmine and jest\n\nDocumentation: https://morganstanley.github.io/ts-mocking-bird/\n\n# Why use this?\n\n![Intellisense Demo](https://github.com/morganstanley/ts-mocking-bird/blob/main/readmeAssets/intellisenseDemo.gif?raw=true)\n\n* All operations fully type safe\n* Mocks interfaces, existing objects and classes\n* Mocks constructor, static functions, static properties as well as instance functions and properties\n* Verifies function calls (with type safe parameter verification), as well as getter and setter calls\n* Replaces imports (again, fully type safe)\n\n# Typescript Version\n\nRequires a minimum Typescript version of 5.0. \n\n# Framework support\n\nThis library has been tested with and supports Jasmine versions 2 - 5, Jest versions 26 - 29 and vitest version 3. The mocking functionality should work in any environment as it has no dependencies on any particular framework.\n\n# Usage\n\n```typescript\nnpm install @morgan-stanley/ts-mocking-bird\n```\n\n## Create a Mock\n\n[Examples](https://github.com/morganstanley/ts-mocking-bird/tree/master/spec/examples/exampleTests.spec.ts)\n\nCreates a mock that is typed as `IMyService`. Properties and functions can be setup using `mockedService`. The actual mocked service is accessible at `mockedService.mock`.\n\n```typescript\nimport {\n    defineProperty,\n    defineStaticProperty,\n    IMocked,\n    Mock,\n    setupFunction,\n    setupProperty,\n    setupStaticFunction,\n} from '@morgan-stanley/ts-mocking-bird';\n\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(\n    setupFunction('functionOne'), // allows the function to be called and allows verification of calls\n    setupFunction('functionTwo', (value: string) =\u003e (value === 'something' ? true : false)), // specifies return value\n    setupProperty('propOne', 'initialValue'),\n    defineProperty('propTwo', () =\u003e 'getter return value', (value: string) =\u003e console.log(`setter called: ${value}`)), // define getter and setter mocks\n);\n\nconst systemUnderTest = new SUT(mockedService.mock); // pass mock instance to system under test\n```\n\n## Mocking a Class with Constructor and Statics\n\nCreates a mock that has statics and can be instantiated using `new mockedService.mock()`.\n\n```typescript\nconst mockedService = Mock.create\u003cMyService, typeof MyService\u003e().setup(\n    setupStaticFunction('staticFunctionOne', () =\u003e 'mockedReturnValue'),\n    defineStaticProperty('staticPropOne', () =\u003e 'mockedStaticGetter'),\n);\n\nconst systemUnderTest = new ClassWithConstructorArgument(mockedService.mockConstructor); // pass mock constructor to system under test\n```\n\n## Verify Calls\n[Examples](https://github.com/morganstanley/ts-mocking-bird/tree/master/spec/examples/exampleTests.spec.ts)\n\n### Adding Custom Matchers\n\nWhen a mock is created using `Mock.create()` the custom matchers that are used by `ts-mocking-bird` are automatically setup in jest, jasmine or vitest - whichever framework you are using. However this can only be done if the creation occurs within a `before` function. If you need to manually setup the custom matchers please call `addMatchers()`:\n\n```typescript\nimport { addMatchers } from '@morgan-stanley/ts-mocking-bird'\n\ndescribe(\"my test\", () =\u003e {\n    beforeEach(() =\u003e {\n        addMatchers();\n    })\n})\n```\n\nFor jasmine this has to be done in a `beforeEach` or `beforeAll` function but for jest and vitest it can be done in the test setup file.\n\n### Verify that a function was called a number of times without checking parameters\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(setupFunction('functionOne'));\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nexpect(mockedService.withFunction('functionOne')).wasCalled(5);\n```\n\n### Verify that a function was called once with specific parameters:\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(setupFunction('functionOne'));\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nexpect(\n    mockedService\n        .withFunction('functionTwo')\n        .withParameters('someValue')\n        .strict(),\n).wasCalledOnce();\n```\n\n**NOTE:** `.withParameters` doe a strict equality check on the value you give it. It you want to see if the values are equal (for example two identical objects that are different instances) use `.withParametersEqualTo`.\n\n### Verify Constructor Parameters\n\n```ts\nconst mockInstance = Mock.create\u003cClassWithInstanceArgument, typeof ClassWithInstanceArgument\u003e().setup(\n            setupConstructor(),\n        );\n\nnew mockInstance.mockConstructor(serviceInstance);\n\nexpect(mockInstance.withConstructor().withParameters(serviceInstance)).wasCalledOnce();\n\n```\n\n### Verify Getter:\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(setupProperty('propOne'));\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nexpect(mockedService.withGetter('propOne')).wasCalledOnce();\n```\n\n### Verify Setter:\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(setupProperty('propOne'));\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nexpect(\n    mockedService\n        .withSetter('propOne')\n        .withParameters('someValue')\n        .strict(),\n).wasCalledOnce();\n```\n\n### Verify that a function was called once and was not called any other times using strict:\n\nIf we use `strict()` we ensure that the function is ONLY called with the specified parameters\n\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e().setup(setupFunction('functionTwo'));\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nsystemUnderTest.functionsTwo('someValue');\nsystemUnderTest.functionsTwo('someOtherValue');\n\nexpect(\n    mockedService\n        .withFunction('functionTwo')\n        .withParameters('someValue')\n        .strict()\n    ).wasCalledOnce(); // this will fail as called twice in total\n\nexpect(\n    mockedService\n        .withFunction('functionTwo')\n        .withParameters('someValue')\n    ).wasCalledOnce(); // this will pass as only called once with params 'someValue'\n```\n\n### Verify function calls using a function verifier returned from `myMock.setupFunction()`:\n```typescript\nconst mockedService: IMocked\u003cIMyService\u003e = Mock.create\u003cIMyService\u003e();\nconst functionVerifier = mockedService.setupFunction('functionTwo');\n\nconst systemUnderTest = new ClassWithInstanceArgument(mockedService.mock);\n\nexpect(functionVerifier.withParameters('someValue')).wasCalledOnce();\n```\n\n## Verify Function Parameters\n[Examples](https://github.com/morganstanley/ts-mocking-bird/tree/master/spec/examples/exampleParameterMatcherTest.spec.ts)\n\n### Verify that function parameters match using strict equality\n```typescript\nconst sampleMock = Mock.create\u003cISampleMocked\u003e().setup(setupFunction('functionOne'));\n\nconst sampleObject: IPerson = { name: 'Fred', id: 1 };\nsampleMock.mock.functionOne('one', 2, sampleObject);\n\nexpect(\n    sampleMock\n        .withFunction('functionOne')\n        .withParameters('one', 2, sampleObject) // strict equality\n    ).wasCalledOnce();\n```\n\n### Verify that function parameter values are equal\n```typescript\nconst sampleMock = Mock.create\u003cISampleMocked\u003e().setup(setupFunction('functionOne'));\n\nsampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });\n\nexpect(\n    sampleMock\n        .withFunction('functionOne')\n        .withParametersEqualTo('one', 2, { name: 'Fred', id: 1 }) // equals used to match\n    ).wasCalledOnce();\n```\n\n### Use alternate matchers\n```typescript\nimport { toBeDefined, any } from \"@morgan-stanley/ts-mocking-bird\"\n\nconst sampleMock = Mock.create\u003cISampleMocked\u003e().setup(setupFunction('functionOne'));\n\nsampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });\n\nexpect(\n    sampleMock\n        .withFunction('functionOne')\n        .withParameters('one', toBeDefined(), any())\n    ).wasCalledOnce();\n```\n\n### Match values with a function\nA function with a signature of `(value: T) =\u003e boolean` can be used to match a parameter value but this will not provide information about what the expected parameter value is in the test failure message.\n```typescript\nconst sampleMock = Mock.create\u003cISampleMocked\u003e().setup(setupFunction('functionOne'));\n\nsampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });\n\nexpect(\n    sampleMock\n        .withFunction('functionOne')\n        .withParameters('one', 2, person =\u003e person.id === 1)\n    ).wasCalledOnce();\n```\n\n### Create a custom `IParameterMatcher` to create more informative failure messages\n```typescript\nconst sampleMock = Mock.create\u003cISampleMocked\u003e().setup(setupFunction('functionOne'));\n\nsampleMock.mock.functionOne('one', 2, { name: 'Fred', id: 1 });\n\nexpect(\n    sampleMock\n        .withFunction('functionOne')\n        .withParameters(toBe('one'), toBe(2), {\n            isExpectedValue: person =\u003e person.id === 1,\n            expectedDisplayValue: 'Person with id 1', // Used to display expected parameter value in failure message\n            parameterToString: person =\u003e `Person with id ${person.id}`, // Used to display value of actual parameters passed in failure message\n        })\n    ).wasCalledOnce();\n```\n\n## Replace Imports\n[Examples](https://github.com/morganstanley/ts-mocking-bird/tree/master/spec/examples/exampleImportReplacementTest.spec.ts)\n\n### Jest Modules\n\nUsing `proxyModule` we proxy all functions and constructors in a module so that they can be replaced at a later point. This allows us to create a new mock implementation of a class or function for each test run and means that concurrent tests are not polluted by the state of previous tests.\n```typescript\nimport { proxyModule, registerMock, reset } from '@morgan-stanley/ts-mocking-bird';\n\nimport * as originalModule from \"modulePath\";\n\nconst proxiedModule = proxyModule(originalModule);\n\ndescribe(\"my-system-under-test\", () =\u003e {\n\n    mockImports(originalModule, proxiedModule);\n\n    beforeEach(() =\u003e {\n        const mockedClass = Mock.create\u003cClassToMock\u003e();\n\n        registerMock(proxiedModule, {ClassToMock: mockedClass})\n    });\n\n    afterEach(() =\u003e {\n        reset(proxiedModule);\n    })\n\n});\n```\n\nUsing `proxyJestModule` we register our proxied module with jest.\n\n```typescript\nimport * as moduleProxy from \"../../relative-import-path\";\n\njest.mock('../../relative-import-path', () =\u003e\n    require('@morgan-stanley/ts-mocking-bird').proxyJestModule(\n        require.resolve('../../relative-import-path'),\n    ),\n);\n\ndescribe(\"my-system-under-test\", () =\u003e {\n\n    beforeEach(() =\u003e {\n        const mockedClass = Mock.create\u003cClassToMock\u003e();\n\n        registerMock(moduleProxy, {ClassToMock: mockedClass})\n    });\n\n    afterEach(() =\u003e {\n        reset(proxiedModule);\n    })\n\n});\n```\nThis works in a node environment (`replaceProperties` does not due to the way require works) and is a more reliable way of mocking imports as jest hoists this mocking code above all other imports so it is guaranteed to run before the members of the module are imported into the system under test. For this to work the following must be observed:\n\n * As the `jest.mock` function is hoisted it can't refer to any variables outside the function. This is why `require('@morgan-stanley/ts-mocking-bird')` is used rather than using an existing import. The import path for the module must also be specified multiple times rather than using a variable for the same reason.\n * The path passed to `jest.mock`, passed to `proxyJestModule` and used to import the `moduleProxy` must all point to same location. For example if a barrel is being imported then all 3 paths must point to same barrel.\n * the path passed to `proxyJestModule` must either be an ambient import such as `fs` or `path`, a non relative import such as `@morgan-stanley/my-dependency-name` or it must be an absolute path. If a relative path such as `../../main/myImport` is used this path will not be resolvable from the `proxyJestModule` function. To get the absolute path use `require.resolve('../../relative-import-path')`\n\n\n\n### Replace an imported function with a mocked function once at the start of your test\n\n```typescript\nimport * as myImport from './exampleImports';\n\ndescribe('replace imports', () =\u003e {\n    const someFunctionMock = () =\u003e 'mockedReturnValue';\n\n    replaceProperties(myImport, { someFunction: someFunctionMock });\n\n    it('should replace function import', () =\u003e {\n        const SUT = new ClassUsingImports('one', 2);\n\n        expect(SUT.someFunctionCallingMockedImport()).toEqual('mockedReturnValue'); // value comes from mock above, not original import\n    });\n});\n```\n\n### Replace an imported function and a class and generate a new mock before each test run\n\n```typescript\nimport * as myImport from './exampleImports';\n\ndescribe('replace imports', () =\u003e {\n\n    describe('create new mock before each test', () =\u003e {\n        let mockService: IMocked\u003cIMyService\u003e;\n        let mockPackage: IMocked\u003ctypeof myImport\u003e;\n\n        replacePropertiesBeforeEach(() =\u003e {\n            mockService = Mock.create\u003cIMyService\u003e();\n            mockPackage = Mock.create\u003ctypeof myImport\u003e().setup(setupFunction('someFunction')); // recreate mocks for each test run to reset call counts\n\n            return [{ package: myImport, mocks: { ...mockPackage.mock, MyService: mockService.mockConstructor } }];\n        });\n\n        it('so that we can assert number of calls', () =\u003e {\n            const SUT = new ClassUsingImports('one', 2);\n\n            expect(SUT.service).toBe(mockService.mock);\n            expect(mockPackage.withFunction('someFunction')).wasNotCalled();\n\n            SUT.someFunctionProxy();\n            expect(mockPackage.withFunction('someFunction')).wasCalledOnce();\n        });\n    });\n});\n```\n\n## Vitest\n\nThis package has been tested with and can be used with `vitest`. In some scenarios it needs to be used in a slightly different way. THis is because by default `vitest` does not use global functions such as `beforeEach`, `expect` and so on. \n\n * if `addMatchers()` is called in a test setup file for example and `vitest` is running in a non global mode then the `expect` function must be passed to `addMatchers`:\n\n```ts\nimport { expect } from \"vitest\";\nimport { addMatchers } from \"@morgan-stanley/ts-mocking-bird\";\n\naddMatchers(expect);\n```\n * if using `replaceProperties` or `replacePropertiesBeforeEach` the `beforeEach`, `afterEach`, `beforeAll` and `afterAll` functions must be passed in when vitest is not running in global mode:\n\n```ts\nimport { beforeAll, afterAll, beforeEach, afterEach} from \"vitest\";\nimport { replaceProperties, replacePropertiesBeforeEach } from \"@morgan-stanley/ts-mocking-bird\";\n\nreplaceProperties(targetObject, mockedProperties, { beforeAll, afterAll });\nreplacePropertiesBeforeEach(() =\u003e {\n    mockService = Mock.create\u003cIMyService\u003e();\n    mockPackage = Mock.create\u003ctypeof myImport\u003e().setup(setupFunction('someFunction'));\n\n    return [{ package: myImport, mocks: { ...mockPackage.mock, MyService: mockService.mockConstructor } }];\n\n}, { beforeEach, afterEach });\n\n```\n\n# Webpack 4 issues\n\nIf you get an error such as\n\n```\nTypeError: Cannot redefine property: BUILD_ID\n```\n\nThis is most likely because webpack 4 uses `configurable:false` when defining properties on import objects. This means that we are unable to replace them when we want to mock them.\n\nThis situation is handled by this mocking library but for it to be fully effective the mocking library needs to be imported before any other code - in other words before webpack has a chance to create any import objects.\n\nTo do this simply import this library before you import your tests or any other code.\n\nFor example:\n\n```typescript\nimport \"@morgan-stanley/ts-mocking-bird\"; // monkey patch Object.defineProperty before any other code runs\n\n// Find all the tests.\nconst context = (require as any).context('./', true, /.spec.ts$/);\n// And load the modules.\ncontext.keys().map(context);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorganstanley%2Fts-mocking-bird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorganstanley%2Fts-mocking-bird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorganstanley%2Fts-mocking-bird/lists"}