Make services easy to test + docs

[bajtos]

This is a follow-up for #1267

When consuming a service using REST connector with template-based configuration: As an app developer, I would definitely want to have few smoke tests to verify that my templates work as intended and match the API provided by the service at the other side. I would like to write an integration test that's using only the service (not the full app!), something along the following lines:

import {GeoService} from '../services/geo.service';
import {expect} from '@loopback/testlab';

describe('GeoService', () => {
  let service: GeoService;
  beforeEach(() => service = new GeoService());

  describe('geocode', () => {
    it('returns geo coords for a given address', () => {
      const result = await service.geocode('107 S B St', 'San Mateo', '94401');
      // { lat: 37.5669986, lng: -122.3237495 }
     expect(result.lat).approximately(37.5669986, 0.5);
     expect(result.lng).approximately(-122.3237495, 0.5);
    });
  });
});

Acceptance criteria

• Finish Feature: a caching HTTP proxy for integration tests #1364 implementing an aggressive caching HTTP proxy to speed up integration tests.
• Finish Add GeoCoder Service to examples/todo #1347 which is adding Geocoder service to Todo example to demonstrate in practice our advices regarding Service testing. Leverage the caching HTTP proxy to keep npm test fast enough. The tricky part: how to configure the Service datasource to use our proxy in the test, but not in production? A poor-man's workaround that may work until we implement proper support for per-env config: the tests can use process.env.PROXY to instruct the underlying request module which is backing our service connectors like loopback-connector-rest.
• Update Todo tutorial - describe how to add Geocoder service - see docs: add geo-coding service to Todo tutorial #1441
• http://loopback.io/doc/en/lb4/Testing-your-application.html#unit-test-your-services: we are not going to write any unit tests for services right now, this section should be removed - see docs: describe how to tests services #1445
• http://loopback.io/doc/en/lb4/Testing-your-application.html#test-your-services-against-real-backends: add content explaining users how to write integration tests, see the code example above for inspiration - see docs: describe how to tests services #1445
• http://loopback.io/doc/en/lb4/Calling-other-APIs-and-web-services.html: add a section about testing services, point readers to best-practices section "test-your-services-against-real-backends". We may need to change the prescribed way of defining Services to make testing easier - see docs: describe how to tests services #1445

[shimks]

Is this a proposal on the service we generate through the CLI tooling?

[bajtos]

let service: GeoService;
  beforeEach(() => service = new GeoService());

☝️ that's out of scope of DP3, as we agreed between @bajtos and @raymondfeng .

However, @bajtos would still like to see an easy way how to test service configuration without App, Context, Controller.

To do so, we need to figure a way how to:

• access data source object/configuration
• call getService to obtain the proxy class

Then the rest of the test can remain as described in the original issue description.

[bajtos]

FWIW, I have already started to look into implementing this user story.

[shimks]

@bajtos For the dev experience of writing integration tests, is something like this sufficient enough? https://github.com/strongloop/loopback-next/blob/master/packages/service-proxy/test/integration/service-proxy.integration.ts. If it isn't, what kind of other functions should we provide so that the users may be able to write their tests more easily?

[bajtos]

IMO, the example tests in service-proxy.integration.ts require the app to share the implementation of the service in many places (inject decorators, integration tests, etc.). Ideally, I'd like both tests and controllers to share the same implementation details of a service.

what kind of other functions should we provide so that the users may be able to write their tests more easily?

That's something I am trying to figure out in #1347. My conclusion so far is that the story "Make services easy to test + docs #1311" is not well defined yet and we need a spike (which I am working on in #1347).

[dhmlau]

@bajtos , since this is in the June milestone, we'd like to get it estimated soon. Is the acceptance criteria good for estimation? From the above comment, it seems like we might need to modify? thanks.

[bajtos]

@dhmlau added two more items to the acceptance criteria. LGTY now?

[bajtos]

Done 🎉