feat(testlab): add StubbedInstanceWithSinonAccessor

Add two new sinon-related helpers to our testlab:

- An interface `StubbedInstanceWithSinonAccessor` describing a stubbed
  instance that provides access to Sinon API for individual methos
  via a `stubs` property.

- A wrapper function `createStubInstance` that calls
  `sinon.createStubInstance` under the hood and returns
  `StubbedInstanceWithSinonAccessor`.

These two new helpers allow unit test to
 - use Sinon in a way that's easy to understand for TypeScript,
 - avoid unnecessary type casts and
 - stay compatible with the upcoming versions of sinon typings.

Author: bajtos

examples/todo-list/test/unit/controllers/todo-list-todo.controller.unit.ts

@@ -3,19 +3,26 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {expect, sinon} from '@loopback/testlab';
-import {TodoListTodoController} from '../../../src/controllers';
-import {TodoList, Todo} from '../../../src/models';
-import {TodoListRepository} from '../../../src/repositories';
-import {givenTodoList, givenTodo} from '../../helpers';
 import {
   DefaultHasManyEntityCrudRepository,
   HasManyRepository,
 } from '@loopback/repository';
+import {
+  createStubInstance,
+  expect,
+  sinon,
+  StubbedInstanceWithSinonAccessor,
+} from '@loopback/testlab';
+import {TodoListTodoController} from '../../../src/controllers';
+import {Todo, TodoList} from '../../../src/models';
+import {TodoListRepository} from '../../../src/repositories';
+import {givenTodo, givenTodoList} from '../../helpers';
 
 describe('TodoController', () => {
-  let todoListRepo: TodoListRepository;
-  let constrainedTodoRepo: HasManyRepository<Todo>;
+  let todoListRepo: StubbedInstanceWithSinonAccessor<TodoListRepository>;
+  let constrainedTodoRepo: StubbedInstanceWithSinonAccessor<
+    HasManyRepository<Todo>
+  >;
 
   /*
   =============================================================================
@@ -113,8 +120,8 @@ describe('TodoController', () => {
   });
 
   function resetRepositories() {
-    todoListRepo = sinon.createStubInstance(TodoListRepository);
-    constrainedTodoRepo = sinon.createStubInstance(
+    todoListRepo = createStubInstance(TodoListRepository);
+    constrainedTodoRepo = createStubInstance<HasManyRepository<Todo>>(
       DefaultHasManyEntityCrudRepository,
     );
 
@@ -139,17 +146,14 @@ describe('TodoController', () => {
       title: aTodoToPatchTo.title,
     });
 
-    todoListRepo.todos = sinon
+    todos = sinon
       .stub()
       .withArgs(aTodoListWithId.id!)
       .returns(constrainedTodoRepo);
-    todos = todoListRepo.todos as sinon.SinonStub;
+    todoListRepo.todos = todos;
 
     // Setup CRUD fakes
-    create = constrainedTodoRepo.create as sinon.SinonStub;
-    find = constrainedTodoRepo.find as sinon.SinonStub;
-    patch = constrainedTodoRepo.patch as sinon.SinonStub;
-    del = constrainedTodoRepo.delete as sinon.SinonStub;
+    ({create, find, patch, delete: del} = constrainedTodoRepo.stubs);
 
     controller = new TodoListTodoController(todoListRepo);
   }

examples/todo-list/test/unit/controllers/todo-list.controller.unit.ts

@@ -3,14 +3,19 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {expect, sinon} from '@loopback/testlab';
+import {
+  createStubInstance,
+  expect,
+  sinon,
+  StubbedInstanceWithSinonAccessor,
+} from '@loopback/testlab';
 import {TodoListController} from '../../../src/controllers';
 import {TodoList} from '../../../src/models';
 import {TodoListRepository} from '../../../src/repositories';
 import {givenTodoList} from '../../helpers';
 
 describe('TodoController', () => {
-  let todoListRepo: TodoListRepository;
+  let todoListRepo: StubbedInstanceWithSinonAccessor<TodoListRepository>;
 
   /*
   =============================================================================
@@ -122,7 +127,7 @@ describe('TodoController', () => {
   });
 
   function resetRepositories() {
-    todoListRepo = sinon.createStubInstance(TodoListRepository);
+    todoListRepo = createStubInstance(TodoListRepository);
     aTodoList = givenTodoList();
     aTodoListWithId = givenTodoList({
       id: 1,
@@ -143,13 +148,15 @@ describe('TodoController', () => {
     });
 
     // Setup CRUD fakes
-    create = todoListRepo.create as sinon.SinonStub;
-    count = todoListRepo.count as sinon.SinonStub;
-    find = todoListRepo.find as sinon.SinonStub;
-    updateAll = todoListRepo.updateAll as sinon.SinonStub;
-    findById = todoListRepo.findById as sinon.SinonStub;
-    updateById = todoListRepo.updateById as sinon.SinonStub;
-    deleteById = todoListRepo.deleteById as sinon.SinonStub;
+    ({
+      create,
+      count,
+      find,
+      updateAll,
+      findById,
+      updateById,
+      deleteById,
+    } = todoListRepo.stubs);
 
     controller = new TodoListController(todoListRepo);
   }

examples/todo-list/test/unit/controllers/todo.controller.unit.ts

@@ -3,14 +3,19 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {expect, sinon} from '@loopback/testlab';
+import {
+  createStubInstance,
+  expect,
+  sinon,
+  StubbedInstanceWithSinonAccessor,
+} from '@loopback/testlab';
 import {TodoController} from '../../../src/controllers';
 import {Todo} from '../../../src/models';
 import {TodoRepository} from '../../../src/repositories';
 import {givenTodo} from '../../helpers';
 
 describe('TodoController', () => {
-  let todoRepo: TodoRepository;
+  let todoRepo: StubbedInstanceWithSinonAccessor<TodoRepository>;
 
   /*
   =============================================================================
@@ -105,7 +110,7 @@ describe('TodoController', () => {
   });
 
   function resetRepositories() {
-    todoRepo = sinon.createStubInstance(TodoRepository);
+    todoRepo = createStubInstance(TodoRepository);
     aTodo = givenTodo();
     aTodoWithId = givenTodo({
       id: 1,
@@ -123,12 +128,14 @@ describe('TodoController', () => {
     });
 
     // Setup CRUD fakes
-    create = todoRepo.create as sinon.SinonStub;
-    findById = todoRepo.findById as sinon.SinonStub;
-    find = todoRepo.find as sinon.SinonStub;
-    updateById = todoRepo.updateById as sinon.SinonStub;
-    replaceById = todoRepo.replaceById as sinon.SinonStub;
-    deleteById = todoRepo.deleteById as sinon.SinonStub;
+    ({
+      create,
+      findById,
+      find,
+      updateById,
+      replaceById,
+      deleteById,
+    } = todoRepo.stubs);
 
     controller = new TodoController(todoRepo);
   }

examples/todo/test/unit/controllers/todo.controller.unit.ts

@@ -4,15 +4,20 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {Filter} from '@loopback/repository';
-import {expect, sinon} from '@loopback/testlab';
+import {
+  createStubInstance,
+  expect,
+  sinon,
+  StubbedInstanceWithSinonAccessor,
+} from '@loopback/testlab';
 import {TodoController} from '../../../src/controllers';
 import {Todo} from '../../../src/models/index';
 import {TodoRepository} from '../../../src/repositories';
 import {GeocoderService} from '../../../src/services';
 import {aLocation, givenTodo} from '../../helpers';
 
 describe('TodoController', () => {
-  let todoRepo: TodoRepository;
+  let todoRepo: StubbedInstanceWithSinonAccessor<TodoRepository>;
   let geoService: GeocoderService;
 
   /*
@@ -135,7 +140,7 @@ describe('TodoController', () => {
   });
 
   function resetRepositories() {
-    todoRepo = sinon.createStubInstance(TodoRepository);
+    todoRepo = createStubInstance(TodoRepository);
     aTodo = givenTodo();
     aTodoWithId = givenTodo({
       id: 1,
@@ -153,12 +158,14 @@ describe('TodoController', () => {
     });
 
     // Setup CRUD fakes
-    create = todoRepo.create as sinon.SinonStub;
-    findById = todoRepo.findById as sinon.SinonStub;
-    find = todoRepo.find as sinon.SinonStub;
-    updateById = todoRepo.updateById as sinon.SinonStub;
-    replaceById = todoRepo.replaceById as sinon.SinonStub;
-    deleteById = todoRepo.deleteById as sinon.SinonStub;
+    ({
+      create,
+      findById,
+      find,
+      updateById,
+      replaceById,
+      deleteById,
+    } = todoRepo.stubs);
 
     geoService = {geocode: sinon.stub()};
     geocode = geoService.geocode as sinon.SinonStub;

packages/repository/test/unit/repositories/relation.factory.unit.ts

@@ -4,7 +4,7 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {Getter} from '@loopback/context';
-import {expect, sinon} from '@loopback/testlab';
+import {createStubInstance, expect} from '@loopback/testlab';
 import {
   createHasManyRepositoryFactory,
   DefaultCrudRepository,
@@ -98,7 +98,7 @@ describe('createHasManyRepositoryFactory', () => {
   }
 
   function givenStubbedCustomerRepo() {
-    customerRepo = sinon.createStubInstance(CustomerRepository);
+    customerRepo = createStubInstance(CustomerRepository);
   }
 
   function givenHasManyDefinition(

packages/repository/test/unit/repositories/relation.repository.unit.ts

@@ -4,7 +4,12 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {Getter} from '@loopback/context';
-import {expect, sinon} from '@loopback/testlab';
+import {
+  createStubInstance,
+  expect,
+  sinon,
+  StubbedInstanceWithSinonAccessor,
+} from '@loopback/testlab';
 import {
   AnyObject,
   Count,
@@ -21,6 +26,10 @@ import {
 } from '../../..';
 
 describe('relation repository', () => {
+  let customerRepo: StubbedInstanceWithSinonAccessor<CustomerRepository>;
+
+  beforeEach(setupStubbedCustomerRepository);
+
   context('HasManyRepository interface', () => {
     /**
      * The class below is declared as test for the HasManyEntityCrudRepository
@@ -67,26 +76,29 @@ describe('relation repository', () => {
       const constraint: Partial<Customer> = {age: 25};
       const HasManyCrudInstance = givenDefaultHasManyCrudInstance(constraint);
       await HasManyCrudInstance.create({id: 1, name: 'Joe'});
-      const createStub = repo.create as sinon.SinonStub;
-      sinon.assert.calledWithMatch(createStub, {id: 1, name: 'Joe', age: 25});
+      sinon.assert.calledWithMatch(customerRepo.stubs.create, {
+        id: 1,
+        name: 'Joe',
+        age: 25,
+      });
     });
 
     it('can find related model instance', async () => {
       const constraint: Partial<Customer> = {name: 'Jane'};
       const HasManyCrudInstance = givenDefaultHasManyCrudInstance(constraint);
       await HasManyCrudInstance.find({where: {id: 3}});
-      const findStub = repo.find as sinon.SinonStub;
-      sinon.assert.calledWithMatch(findStub, {where: {id: 3, name: 'Jane'}});
+      sinon.assert.calledWithMatch(customerRepo.stubs.find, {
+        where: {id: 3, name: 'Jane'},
+      });
     });
 
     context('patch', async () => {
       it('can patch related model instance', async () => {
         const constraint: Partial<Customer> = {name: 'Jane'};
         const HasManyCrudInstance = givenDefaultHasManyCrudInstance(constraint);
         await HasManyCrudInstance.patch({country: 'US'}, {id: 3});
-        const patchStub = repo.updateAll as sinon.SinonStub;
         sinon.assert.calledWith(
-          patchStub,
+          customerRepo.stubs.updateAll,
           {country: 'US', name: 'Jane'},
           {id: 3, name: 'Jane'},
         );
@@ -105,8 +117,10 @@ describe('relation repository', () => {
       const constraint: Partial<Customer> = {name: 'Jane'};
       const HasManyCrudInstance = givenDefaultHasManyCrudInstance(constraint);
       await HasManyCrudInstance.delete({id: 3});
-      const deleteStub = repo.deleteAll as sinon.SinonStub;
-      sinon.assert.calledWith(deleteStub, {id: 3, name: 'Jane'});
+      sinon.assert.calledWith(customerRepo.stubs.deleteAll, {
+        id: 3,
+        name: 'Jane',
+      });
     });
   });
 
@@ -128,14 +142,15 @@ describe('relation repository', () => {
     }
   }
 
-  let repo: CustomerRepository;
+  function setupStubbedCustomerRepository() {
+    customerRepo = createStubInstance(CustomerRepository);
+  }
 
   function givenDefaultHasManyCrudInstance(constraint: DataObject<Customer>) {
-    repo = sinon.createStubInstance(CustomerRepository);
     return new DefaultHasManyEntityCrudRepository<
       Customer,
       typeof Customer.prototype.id,
       CustomerRepository
-    >(Getter.fromValue(repo), constraint);
+    >(Getter.fromValue(customerRepo), constraint);
   }
 });

packages/testlab/src/sinon.ts

@@ -3,7 +3,37 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import sinon = require('sinon');
+import * as sinon from 'sinon';
 import {SinonSpy} from 'sinon';
 
 export {sinon, SinonSpy};
+
+export type StubbedInstanceWithSinonAccessor<T> = T & {
+  stubs: sinon.SinonStubbedInstance<T>;
+};
+
+/**
+ * Creates a new object with the given functions as the prototype and stubs all
+ * implemented functions.
+ *
+ * Note: The given constructor function is not invoked. See also the stub API.
+ *
+ * This is a helper method replacing `sinon.createStubInstance` and working
+ * around the limitations of TypeScript and Sinon, where Sinon is not able to
+ * list private/protected members in the type definition of the stub instance
+ * and therefore the stub instance cannot be assigned to places expecting TType.
+ * See also
+ *  - https://github.com/Microsoft/TypeScript/issues/13543
+ *  - https://github.com/DefinitelyTyped/DefinitelyTyped/issues/14811
+ *
+ * @template TType Type being stubbed.
+ * @param constructor  Object or class to stub.
+ * @returns A stubbed version of the constructor, with an extra property `stubs`
+ * providing access to stub API for individual methods.
+ */
+export function createStubInstance<TType>(
+  constructor: sinon.StubbableType<TType>,
+): StubbedInstanceWithSinonAccessor<TType> {
+  const stub = sinon.createStubInstance(constructor);
+  return Object.assign(stub as TType, {stubs: stub});
+}