1 | # Typescript Mock Imports
|
2 |
|
3 | #### Intuitive mocking for Typescript class imports.
|
4 |
|
5 | [![Build Status](https://travis-ci.org/EmandM/ts-mock-imports.svg)](https://travis-ci.org/EmandM/ts-mock-imports)
|
6 |
|
7 | ## Installation
|
8 |
|
9 | `npm install ts-mock-imports --save-dev`
|
10 |
|
11 | ## About
|
12 |
|
13 | ts-mock-imports is useful if you want to replace classes that are exported from local files with stub versions of those classes. This allows ES6 code to be easily unit-tested without the need for a dependency injection library.
|
14 |
|
15 | ts-mock-imports is built on top of sinon.
|
16 |
|
17 | The mocked class takes all of the original class functions, and replaces them with noop functions (functions returning `undefined`).
|
18 |
|
19 | This library needs to be run on TypeScript 2.6.1 or later.
|
20 |
|
21 | ## Usage
|
22 |
|
23 | `src/foo.ts`
|
24 | ```javascript
|
25 | export class Foo {
|
26 | constructor() {
|
27 | throw new Error();
|
28 | }
|
29 | }
|
30 | ```
|
31 |
|
32 | `src/bar.ts`
|
33 | ```javascript
|
34 | import { Foo } from './foo';
|
35 |
|
36 | export class Bar {
|
37 | constructor() {
|
38 | const foo = new Foo();
|
39 | }
|
40 | }
|
41 | ```
|
42 |
|
43 | `test/bar.spec.ts`
|
44 | ```javascript
|
45 | import ImportMock from 'ts-mock-imports';
|
46 | import { Bar } from './Bar';
|
47 | import * as fooModule from '../src/foo';
|
48 |
|
49 | // Throws error
|
50 | const bar = new Bar();
|
51 |
|
52 | const mockManager = ImportMock.mockClass(fooModule, 'Foo');
|
53 |
|
54 | // No longer throws an error
|
55 | const bar = new Bar();
|
56 |
|
57 | // Call restore to reset to original imports
|
58 | mockManager.restore();
|
59 | ```
|
60 |
|
61 | ## API
|
62 | **`mockClass(module: <import * as>, importName?: string ): MockManager<T>`**
|
63 |
|
64 | **module:**
|
65 |
|
66 | The module containing the class you would like to mock.
|
67 |
|
68 | Both the source file and test file need to use the same path to import the mocked module. I.e. Cannot use `'src/index'` to import into the `.spec.ts` file and then use `'src/foo'` to import into `bar.ts`. Both files need to use either `'src/foo'` or `'src/index'`.
|
69 |
|
70 | **importName:**
|
71 |
|
72 | What the class is exported as. If exported using `export default` then this parameter is not needed.
|
73 |
|
74 | Using importName:
|
75 | ```javascript
|
76 | // export class Foo
|
77 | import * as fooModule from '../src/foo';
|
78 |
|
79 | const mockManager = ImportMock.mockClass(fooModule, 'Foo');
|
80 | ```
|
81 |
|
82 | Default imports:
|
83 | ```javascript
|
84 | // export default Foo
|
85 | import * as foo from '../foo';
|
86 |
|
87 | const mockManager = ImportMock.mockClass(foo);
|
88 | ```
|
89 |
|
90 | Import mock will infer the type of `Foo` if it is the only item exported out of it's file. If more things are exported, you will need to explicitly provide types to Import mock.
|
91 |
|
92 | Explicit typing:
|
93 | ```javascript
|
94 | import * as fooModule from '../foo';
|
95 |
|
96 | const mockManager = ImportMock.mockClass<fooModule.Foo>(fooModule, 'Foo');
|
97 | ```
|
98 |
|
99 | If you wish to ensure that `Foo` is the correct name for the mocked class, give import mock the type of your module.
|
100 |
|
101 | Explicit typing with full type assurance
|
102 | ```javascript
|
103 | import * as fooModule from '../foo';
|
104 |
|
105 | const mockManager = ImportMock.mockClass<fooModule.Foo, typeof fooModule>(fooModule, 'Foo');
|
106 |
|
107 | // Will result in a TS Error as Bar is not exported by Foo
|
108 | const mockManager = ImportMock.mockClass<fooModule.Foo, typeof fooModule>(fooModule, 'Bar');
|
109 | ```
|
110 |
|
111 | ---
|
112 |
|
113 | **`mockStaticClass(module: <import * as>, importName?: string ): MockStaticManager<T>`**
|
114 |
|
115 | Takes the same arguments as `mockClass` but only replaces static functions on the original class.
|
116 |
|
117 | Static classes:
|
118 | (Only recreates static methods)
|
119 | ```javascript
|
120 | import * as fooModule from '../foo';
|
121 |
|
122 | const mockManager = ImportMock.mockStaticClass(fooModule, 'Foo');
|
123 | ```
|
124 |
|
125 | ---
|
126 |
|
127 | **`MockManager<T>.mock(functionName: string, returns?: any): SinonStub`**
|
128 |
|
129 | This function returns a sinon stub object.
|
130 |
|
131 | **functionName:**
|
132 |
|
133 | The name of the function you would like to mock.
|
134 |
|
135 | If using MockManager, Typescript expects the functionName to match functions availablel on the original class.
|
136 |
|
137 | MockStaticManager allows any string.
|
138 |
|
139 | **returns:**
|
140 |
|
141 | The value returned when the mocked function is called.
|
142 |
|
143 |
|
144 | Mocking functions:
|
145 | (Returns a sinon stub)
|
146 | ```javascript
|
147 | import * as fooModule from '../foo';
|
148 |
|
149 | const fooManager = ImportMock.mockClass(fooModule, 'Foo');
|
150 |
|
151 | // Will throw a type error if bar() does not exist on Foo
|
152 | const sinonStub = fooManager.mock('bar');
|
153 | ```
|
154 |
|
155 | Mocking functions with a return object:
|
156 | ```javascript
|
157 | import * as fooModule from '../foo';
|
158 |
|
159 | const mockManager = ImportMock.mockClass(fooModule, 'Foo');
|
160 |
|
161 | const returnVal = 'Bar';
|
162 | const sinonStub = mockManager.mock('bar', returnVal);
|
163 | // new Foo().bar() now returns 'Bar'
|
164 | ```
|
165 |
|
166 | ---
|
167 |
|
168 | **`MockManager<T>.getMockInstance(): T`**
|
169 |
|
170 | Returns an instance of the mocked class.
|
171 | ```javascript
|
172 | import * as fooModule from '../foo';
|
173 |
|
174 | const mockManager = ImportMock.mockClass(fooModule, 'Foo');
|
175 |
|
176 | const sinonStub = mockManager.mock('bar', 'Bar');
|
177 | const mockFoo = mockManager.getMockInstance();
|
178 | mockFoo.bar() // returns 'Bar'
|
179 | ```
|
180 | ---
|
181 |
|
182 | **`MockManager<T>.restore()`**
|
183 |
|
184 | Restores the import back to the original class.
|
185 |
|
186 | It is important that this is called so future imports work as expected.
|
187 |
|
188 |
|
189 |
|
190 | ## Test
|
191 |
|
192 | ```
|
193 | npm run test
|
194 | ```
|
195 |
|
196 | ### Test Types
|
197 |
|
198 | ```
|
199 | npm run dtslint
|
200 | ```
|
201 |
|
202 | ### Unit Tests
|
203 |
|
204 | ```
|
205 | npm run unit-test
|
206 | ``` |
\ | No newline at end of file |