docs(ngMock): add verifyNoOutstandingExpectation digest parameter

[glebec]

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

Docs update.

What is the current behavior? (You can also link to an open issue here)

Undocumented yet public API — parameter digest of $httpBackend.verifyNoOutstandingExpectation was previously not listed.

What is the new behavior (if this is a feature change)?

Now explained along with motivating use case.

Does this PR introduce a breaking change?

No.

Please check if the PR fulfills these requirements

• The commit message follows our guidelines: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format

Other information:

add detailed documentation, with motivation, for the previously-undocumented
verifyNoOutstandingExpectation parameter digest.

[gkalpak]

I think this was intentionally undocumented.
There are several APIs that (although exposed) are considered "proprietary"/private and thus remain undocumented.

Do you have a usecase, where this parameter is necessary ?

[glebec]

I'll see if I can make a Plnkr or similar to demonstrate, but in short, under certain testing conditions (including the ones in the current documentation!) if a spec fails in certain ways then a misleading / extraneous "digest in progress" error can be thrown unless false is passed.

[glebec]

Here is a demo Plnkr. TestA shows setup according to the Angular docs. TestB shows using the false param (undocumented). If your tests all do a flush and your afterEachs all do a verifyNoOutstandingExpectation, a rejected promise can cause an extraneous $digest in progress which isn't really related to the test failure reason. Using false prevents the unnecessary double digest and narrows the report down to the actual relevant issue.

PS — if you want to leave this undocumented, might a comment to that effect (e.g. // param digest intentionally undocumented) be advisable?

[gkalpak]

TBH, I'm not too keen on documenting it. Since you are getting the actual error (plus another one about the $digest), you should be able to fix it (although it's not an ideal situation).

Even if it were "public" API, using it in every test isn't a good idea, so you would probably run into the same errors. Plus it would give people another way to shoot themselves in the foot.

A more appropriate "countermeasure" might be to check if a $digest is in progress and not invoke a new one inside verifyNoOutstandingExpectation().

WDYT

[glebec]

A more appropriate "countermeasure" might be to check if a $digest is in progress and not invoke a new one inside verifyNoOutstandingExpectation().

That sounds promising, I'll look into making a PR for it.

[glebec]

I'm going to let others possibly tackle this for the foreseeable future, as the case I illustrated with the Plunker seems to be illustrating something much deeper and odder going on with thrown exceptions inside of $q handlers being somehow caught by Jasmine even though they are supposed to result in a rejected promise — and this all interacting with the verify call, which is SUPER weird. Will take a lot more research to figure out what really the root problem is and how it ought to be fixed — I don't quite have that much free time at the moment.