Introduction
Spies in the Katsa extension is modeled as four distinct calls that can be organized along two different dimensions. They are either doing logging or error reporting, and they are either just giving a notification or a stack trace. It is easy to extend the default behavior through use of callbacks, thus keeping the expected behavior. One typical use is to extend the granularity past the just info logging and error reporting.
The intention with this extension is to enable inspection of simple state visits in test doubles, as implemented by the Doppelgänger extension. Intention is not to implement assertions, that is part of the Expect extension.
The name “katsa” denotes a field intelligence officer in Mossad, the national intelligence agency of Israel. A katsa collects information and runs agents – spies – like this extension. This extension has software spies that track code execution.
Examples
A core example of a module can be found at Module:Test. This example registers four spies, one for each of carp(), cluck(), croak(), and confess().
When called they give a resulting output as described by the following. The previous example module and the following wikipages can be loaded by calling composer import in the Katsa extension directory.
Carp
The following line should not give a visible output, it should only give output in the console.
{{#invoke:Test|carp}}
This is the lowest level reporting, it gives only a one-liner, and only in the console.
Cluck
The following line should not give a visible output, it should only give output in the console.
{{#invoke:Test|cluck}}
This is the next level, and it gives an additional stack trace. Still, it is only reporting in the console.
Croak
The following line should give an error message reading “Lua error: Croak called: croak croak croak.”
{{#invoke:Test|croak}}
This is a critical level and moves the reporting from the console and into the output page. Again it is only a one-liner, but in bright red color. Usually this should only be used for critical actions that can't be fulfilled without user interactions.
Confess
The following line should give an error message reading “Lua error in Module:Test at line 22: Confess called: confess confess confess.” The line number can change somewhat.
{{#invoke:Test|confess}}
This is also a critical level and produces an error message in bright red color. It gives a stack trace, and should only be used for critical actions that can't be fulfilled without user interactions.