Spy on function objects

[bllanos]

Requested reviewers: @bsleighb Issues: #10

Summary of Changes

• Function calls have their arguments and return values recorded
• Reporters output function call event information

  Detailed Changes

  Object wrapper code

• If the object to be wrapped is a function, a function is defined which proxies calls to the object.
  • Consequently, the original object may be modified by calls to the wrapper object.
  • I couldn't find a better way to observe function call behaviour, as it isn't possible to copy code from one function to another. (If it was, it would probably not preserve bindings to external variables. If it was, and did preserve variable bindings, then there would still be unwanted side effects from calling the function.)
• Arguments passed to the wrapped object are recorded after the call completes, such that the call has already mutated the arguments. There are two reasons for not recording argument values before the call to the wrapped object:
  • The focus of object-spy is firstly on how the client code sees the spy object. Side effects are part of this "perception".
  • It is simpler to implement.
• In any case, would be a simple extension to capture argument values both before and after a function call.
• Some refactoring in order to pass the complete options object around when appropriate.

  Observation event format

• Instead of storing values, the serialize-javascript module is used to obtain string versions of values.
  • This is better than cloning objects, as the lodash cloneDeep method cannot clone functions, for example.
  • Strings are immutable, eliminating the chance for stored values to be mutated later.
• Added a function call component to observation data, stored under the callData key
  • Function call events come in two sub-types:
  • call returned value
  • call threw exception
  • Function call events are distinguishable from other events because they have arguments attributes.
  • The value attribute of function call events stores the return value or thrown exception, as appropriate.

    Observation event storage

• Added a new class, CallStore, to store function call events.
  • This class is then used by the StoreManager class.
• The CallStore class can be configured to store non-primitive values or not. This will affect memory usage, and report generation. (Reports will not be able to show the values of arguments and return values, regardless of report generation options, if non-primitive values are not stored.)
  • Control over this behaviour is exposed by the copyCallObjectValues option passed to watch() in src/watch/watch.coffee.

    Reporter output

• The paths of events is now prefixed with .. This makes the path string non-empty for a call to an object that is a function. (I thought that empty paths were visually confusing, and they also caused problems with the report generation code.)

  LogStyleReporter

• Added the following report generation options
  • Show argument lists as part of function call events
  • Show non-primitive values as part of argument lists and return value display
  • Defaults to false in order to avoid cluttering the report.
• Removed the type column of the report output
  • It was redundant.
  • It makes little sense when there are multiple values being displayed (i.e. arguments and return values).
  • When values are not displayed (as intended, or because they are not stored), their types will be shown in their place.

    Constants

• Split the OBSERVATION_CATEGORIES into sub-categories; one for function call events and another for property-related events.
  • I added a third, commented-out category for object-level events that may be used in the future (but probably only if Object.observe() is available).

    Testing Performed

• Manual testing to verify that the above-mentioned changes are effective.
  • Tested report output following the use of each combination of the copyCallObjectValues option passed to watch() and the showArguments and showObjectValues options passed to the LogStyleReporter class.
  • Tested output of non-primitive values (functions and objects) by the LogStyleReporter class.

    Aspects of #10 not implemented

• Function call durations are not being recorded. Call duration calculation would be a simple extension, however.

  To-do

• [x] Update wiki pages
• [x] Update the README

[ghost]

So after running the project locally and creating a function that only console.log'd, it seems, as we discovered, there is a problem when a function returns undefined.

The following error occurs:

objectSpy error: Unknown type of call event passed to CallStore.add()

[bllanos]

I made several updates:

• It is now possible for a function to return or throw undefined values.
• Changed the way in which the library avoids wrapping built-in properties of functions. I now create a list of built-in properties by collecting the property names that exist when a function is first created. This list is used as a blacklist when wrapping the object.
  • This has the benefit of eliminating a lot of redundant logging output.

@bsleighb if you can run a sanity check, I would appreciate it.

[ghost]

Works as advertised now :+1: