docs: add stub service section

[b-admike]

Fixes #2101

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

• npm test passes on your machine
• New tests added or existing tests modified to cover all changes
• Code conforms with the style guide
• API Documentation in code was updated
• Documentation in /docs/site was updated
• Affected artifact templates in packages/cli were updated
• Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

[jannyHou]

nitpick: // before the sentence.

[b-admike]

This is explaining the step that is about to happen like Configure the geocode method as a stub and its behaviour before your test(s): above, so it's not meant to be a comment. WDYT @jannyHou?

[jannyHou]

Hmm, where is '1600 Pennsylvania Ave NW' used in the previous code?

[b-admike]

Good question. It's not apparent here, but the way we structure our test is to arrange, act, then assert, so somewhere in the act phase, we'd call a controller method that eventually calls the geoService.geocode() with the given address string. I don't show that here because I thought it would be apparent, but I can add a note for that to make it clear.

[jannyHou]

I see, thank you for the explanation and good document 👍

[nabdelgadir]

I tried it with the following setup:

import {GeocoderService} from './geocoder.service';
const GeoPoint = require('geopoint');

export class DummyGeocoder implements GeocoderService {
  // in practice, the constructor could take an API key to authenticate with
  // the service proxy provider
  constructor() {}

  geocode(address: string) {
    // this would call the remote API for the real coordinates
    return new GeoPoint(address);
  }
}

Test:

import {DummyGeocoder} from '../../../services/dummy.service';
import {sinon} from '@loopback/testlab';

describe('GeoCoderController', () => {
  let geoService: DummyGeocoder;
  beforeEach(givenStubbedService);

  // your unit tests

  it('', () => {
    const geocodeStub = geoService.geocode as sinon.SinonStub;
    geocodeStub.resolves([{y: 0, x: 0}]);

    sinon.assert.calledWithMatch(geocodeStub, '1600 Pennsylvania Ave NW');
  });

  function givenStubbedService() {
    geoService = sinon.createStubInstance(DummyGeocoder);
  }
});

But it fails with AssertError: expected geocode to be called with match. geocode never gets called, so is there something wrong with the setup?

[b-admike]

I tried it with the following setup:

import {GeocoderService} from './geocoder.service';
const GeoPoint = require('geopoint');

export class DummyGeocoder implements GeocoderService {
  // in practice, the constructor could take an API key to authenticate with
  // the service proxy provider
  constructor() {}

  geocode(address: string) {
    // this would call the remote API for the real coordinates
    return new GeoPoint(address);
  }
}

Test:

import {DummyGeocoder} from '../../../services/dummy.service';
import {sinon} from '@loopback/testlab';

describe('GeoCoderController', () => {
  let geoService: DummyGeocoder;
  beforeEach(givenStubbedService);

  // your unit tests

  it('', () => {
    const geocodeStub = geoService.geocode as sinon.SinonStub;
    geocodeStub.resolves([{y: 0, x: 0}]);

    sinon.assert.calledWithMatch(geocodeStub, '1600 Pennsylvania Ave NW');
  });

  function givenStubbedService() {
    geoService = sinon.createStubInstance(DummyGeocoder);
  }
});

But it fails with AssertError: expected geocode to be called with match. geocode never gets called, so is there something wrong with the setup?

Thanks for trying it out @nabdelgadir. This is missing the act stage of the test between the arrange/ setup of the test and the assertion for the expected result. A good example to that would be https://github.com/strongloop/loopback-next/blob/master/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts#L66. That would invoke the geocode method with the address string and then the assertion should work. I'll add an assertion in that test and refer to it in the docs.

[dhmlau]

From the github view, the this doesn't show the link. do you mean:

[this](https://github.com/strongloop/loopback-next/blob/master/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts#L53-L71)

Also, I'm not sure specifying the line number would be a good solution in general, because they tend to get outdated easily. But I'm not sure if specifying the test case name would be a good alternative either. Just wanna bring this up. Thanks.

[bajtos]

1. Let's use a more descriptive link name than "this". For example, "TodoController unit tests".

2. Either point to the entire file in master branch (https://github.com/strongloop/loopback-next/blob/master/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts) or lock down the commit sha in a link pointing to line numbers (https://github.com/strongloop/loopback-next/blob/bd0c45033503f631a533ad6176620354d9cf6768/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts#L53-L71).

[b-admike]

Yes I was looking for the commit sha, thank you both for pointing this out :-).

[bajtos]

The changes look good at high level, let's discuss few details.

[bajtos]

1. Let's use a more descriptive link name than "this". For example, "TodoController unit tests".

2. Either point to the entire file in master branch (https://github.com/strongloop/loopback-next/blob/master/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts) or lock down the commit sha in a link pointing to line numbers (https://github.com/strongloop/loopback-next/blob/bd0c45033503f631a533ad6176620354d9cf6768/examples/todo/src/__tests__/unit/controllers/todo.controller.unit.ts#L53-L71).

[b-admike]

@bajtos @dhmlau @jannyHou @nabdelgadir I think I've applied all your feedback. LGTY now?

[bajtos]

👏

[nabdelgadir]

LGTM besides a nitpick 👍

[nabdelgadir]

Nitpick: GeoCoderService -> GeocoderService (there's a few other instances below nvm, just one)

[jannyHou]

💯 LGTM

[dhmlau]

I'm not familiar with the stub service, but you've addressed my question/concern.