Package brave.test

Class IntegrationTestSpanHandler

java.lang.Object

brave.handler.SpanHandler

brave.test.IntegrationTestSpanHandler

All Implemented Interfaces:

org.junit.rules.TestRule

public final class IntegrationTestSpanHandler
extends SpanHandler
implements org.junit.rules.TestRule

This is a special span reporter for remote integration tests.

Ex. The following is similar to our base test class ITRemote:

{@code

Since:

5.12

See Also:

TestSpanHandler

Nested Class Summary

Nested classes/interfaces inherited from class brave.handler.SpanHandler

SpanHandler.Cause

Field Summary

Fields inherited from class brave.handler.SpanHandler

NOOP

Constructor Summary

Constructors

Constructor	Description
IntegrationTestSpanHandler()

Method Summary

Modifier and Type	Method	Description
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)
boolean	begin(TraceContext context, MutableSpan span, TraceContext parent)
boolean	end(TraceContext context, MutableSpan span, SpanHandler.Cause cause)
boolean	handlesAbandoned()
void	ignoreAnySpans()	Call this before throwing an AssumptionViolatedException, when there's a chance a span was finished.
MutableSpan	takeLocalSpan()	Blocks until a local span was finished.
MutableSpan	takeRemoteSpan(Span.Kind kind)	Blocks until a remote span was finished.
MutableSpan	takeRemoteSpanWithError(Span.Kind kind)	Some frameworks swallow exceptions.
MutableSpan	takeRemoteSpanWithError(Span.Kind kind, Throwable error)	Like takeRemoteSpan(Kind) except a MutableSpan.error() must equal the given value.
MutableSpan	takeRemoteSpanWithErrorMessage(Span.Kind kind, String errorMessage)	Use instead of takeRemoteSpanWithError(Kind, Throwable) when you cannot catch a reference to the actual raised exception during a test.
MutableSpan	takeRemoteSpanWithErrorTag(Span.Kind kind, String errorTag)	Like takeRemoteSpan(Kind) except an error tag must match the given value.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

IntegrationTestSpanHandler

public IntegrationTestSpanHandler()

Method Detail

ignoreAnySpans

public void ignoreAnySpans()

Call this before throwing an AssumptionViolatedException, when there's a chance a span was finished.

This was made for detecting features in HTTP server testing via 404. When 404 itself is instrumented, post-conditions would otherwise fail from not consuming the associated span.

takeLocalSpan

public MutableSpan takeLocalSpan()

Blocks until a local span was finished. This does not verify errors.

takeRemoteSpan

public MutableSpan takeRemoteSpan(Span.Kind kind)

Blocks until a remote span was finished. We define a remote span as one with a timestamp, duration and kind.

This will fail if there's an MutableSpan.error() or an "error" tag. If you expect a failure, use takeRemoteSpanWithError(Kind, Throwable) or takeRemoteSpanWithErrorTag(Kind, String) instead.

takeRemoteSpanWithError

public MutableSpan takeRemoteSpanWithError(Span.Kind kind,
                                           Throwable error)

Like takeRemoteSpan(Kind) except a MutableSpan.error() must equal the given value.

Note: This enforces there is no "error" tag. If your framework clarifies the "error" tag when there is also an unhandled exception, use takeRemoteSpanWithErrorTag(Kind, String) first, then check for error using normal assertions.

See Also:

takeRemoteSpanWithError(Kind), takeRemoteSpanWithErrorMessage(Kind, String), takeRemoteSpanWithErrorTag(Kind, String)

takeRemoteSpanWithError

public MutableSpan takeRemoteSpanWithError(Span.Kind kind)

Some frameworks swallow exceptions. This tests that either an "error" tag exists or MutableSpan.error() does, without regards to the value.

See Also:

takeRemoteSpanWithError(Kind, Throwable), takeRemoteSpanWithErrorMessage(Kind, String), takeRemoteSpanWithErrorTag(Kind, String)

takeRemoteSpanWithErrorMessage

public MutableSpan takeRemoteSpanWithErrorMessage(Span.Kind kind,
                                                  String errorMessage)

Use instead of takeRemoteSpanWithError(Kind, Throwable) when you cannot catch a reference to the actual raised exception during a test.

This is typically used when testing framework errors result in a finished span.

See Also:

takeRemoteSpanWithError(Kind, Throwable), takeRemoteSpanWithError(Kind), takeRemoteSpanWithErrorTag(Kind, String)

takeRemoteSpanWithErrorTag

public MutableSpan takeRemoteSpanWithErrorTag(Span.Kind kind,
                                              String errorTag)

Like takeRemoteSpan(Kind) except an error tag must match the given value.

See Also:

takeRemoteSpanWithError(Kind, Throwable), takeRemoteSpanWithError(Kind), takeRemoteSpanWithErrorMessage(Kind, String)

begin

public boolean begin(TraceContext context,
                     MutableSpan span,
                     @Nullable
                     TraceContext parent)

Overrides:

begin in class SpanHandler

handlesAbandoned

public boolean handlesAbandoned()

Overrides:

handlesAbandoned in class SpanHandler

end

public boolean end(TraceContext context,
                   MutableSpan span,
                   SpanHandler.Cause cause)

Overrides:

end in class SpanHandler

apply

public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base,
                                               org.junit.runner.Description description)

Specified by:

apply in interface org.junit.rules.TestRule

toString

public String toString()

Overrides:

toString in class Object