Package ru.vyarus.dropwizard.guice.test.jupiter.ext.track

Annotation Interface TrackBean

@Retention(RUNTIME) @Target(FIELD) public @interface TrackBean
Tracks method calls on any guice bean and records arguments and return values, together with measuring time.

Useful for validating called method arguments and return value (when service called indirectly - by another top-level service). In this sense it is very close to mockito spy (SpyBean), but api is simpler. Tracker collects both raw in/out objects and string (snapshot) version (because mutable objects could change). Raw objects holding could be disabled with keepRawObjects().

Another use-case is slow methods detection: tracker counts each method execution time, and after test could print a report indicating the slowest methods. Or it could be used to simply print all called methods to console with trace() (could be useful during behavior investigations). Another option is to configure a slow method threshold: then only methods above a threshold would be logged with WARN.

Example usage: @TrackBean Tracker<Service> tracker. All calls to Service bean would be tracked. The field might be static.

Manual field initialization is not allowed.

Tracking is implemented with a custom AOP handler which intercepts all bean calls and record them.

Can be used together with mocks, spies or stubs (MockBean, SpyBean, StubBean).

Guicey extension debug (TestGuiceyApp.debug()) enables tracker fields debug: all recognized annotated fields would be printed to console. Also, after each test method it would print performance stats for called methods in all registered trackers.

Individual tracker report could be enabled with printSummary() - will print called methods stats for exact tracker (independent of guicey extension debug option).

By default, tracker re-set after each test method. Use autoReset() to collect tracking data for the entire test.

Limitation: could track only beans, created by guice (due to used AOP). Does not work for HK2 beans.

Since:
11.02.2025

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    autoReset
    Note: tracker could be cleared manually with Tracker.clear().
    boolean
    keepRawObjects
    It is more likely that trackers would be used mostly for "call and verify" scenarios where keeping raw arguments makes perfect sense.
    int
    maxStringLength
    Required to keep called method toString rendering readable in case of large strings used.
    boolean
    printSummary
    Note that the summary for all registered trackers is printed when the guicey extension debug option enabled.
    long
    slowMethods
    Print warnings about methods executing longer than the specified threshold.
    ChronoUnit
    slowMethodsUnit
    Unit for slowMethods() threshold value (seconds by default).
    boolean
    trace
    When enabled, prints called method just after it's execution (with called arguments and returned result).

  • Element Details

    • trace

      boolean trace
      When enabled, prints called method just after it's execution (with called arguments and returned result). Not enabled by default to avoid output mess in case when many methods would be called during test.
      Returns:
      true to print each method execution
      Default:
      false

    • slowMethods

      long slowMethods
      Print warnings about methods executing longer than the specified threshold. Set to 0 to disable warnings.
      Returns:
      slow method threshold (in seconds, by default - see slowMethodsUnit())
      Default:
      5L

    • slowMethodsUnit

      ChronoUnit slowMethodsUnit
      Unit for slowMethods() threshold value (seconds by default).
      Returns:
      unit for threshold value
      Default:
      SECONDS

    • keepRawObjects

      boolean keepRawObjects
      It is more likely that trackers would be used mostly for "call and verify" scenarios where keeping raw arguments makes perfect sense. That's why it's enabled by default.

      Important: method arguments and the result objects state could be mutable and change after or during method execution (and so be irrelevant for tracks analysis). For such cases, the tracker always holds string representations of method arguments and the result (rendered in method execution time).

      It makes sense to disable option if too many method executions appear during the test (e.g., tracker used for performance metrics).

      Returns:
      true to keep raw arguments and result objects
      Default:
      true

    • maxStringLength

      int maxStringLength
      Required to keep called method toString rendering readable in case of large strings used. Note that for non-string objects, an object type with identity hash would be shown (not rely on toString because it would be too much unpredictable).
      Returns:
      maximum length of string in method parameter or returned result
      Default:
      30

    • autoReset

      boolean autoReset
      Note: tracker could be cleared manually with Tracker.clear().
      Returns:
      true to reset tracker (remove collected stats) after each test method
      Default:
      true

    • printSummary

      boolean printSummary
      Note that the summary for all registered trackers is printed when the guicey extension debug option enabled. This option exists to be able to print summary for a single tracker, independent of the debug option.

      The report would be shown after each test method.

      Note that such reports could be built at any time manually with tracker.getStats().render() (or any custom report using tracker.getStats().getMethods()).

      Returns:
      true to print summary after test
      Default:
      false