Inherits from NSObject
Declared in SLLogger.h

Overview

The shared SLLogger used by Subliminal to log test progress. It may also be used by tests, and by the application itself, to log custom messages to the test output.

SLLogger logs messages to the Automation instrument. Its output can be viewed in the Instruments application when the tests are running locally, and in the console while the instruments command-line tool is running.

When running subliminal-test from the command line, instruments will also produce a .trace file inside the specified output directory, which file can be opened in the Instruments application after the tests have concluded.

When errors or warnings are logged, the SLLogger will direct the Automation instrument to take a screenshot of the application. Those screenshots can be viewed in Instruments alongside log messages when the tests are running locally, or by opening the .trace file produced when running the subliminal-test command-line tool having specified an output directory. subliminal-test will also save such screenshots to the specified output directory.

Providing alternate log formats

SLLogger is not designed to be subclassed, because the Automation instrument is the only way for tests running on a device to report their status to the test runner. However, when the subliminal-test command-line tool is invoked with an output directory, it will save the logs to that directory as a .plist, with all log events available as structured dictionaries. That .plist may be parsed into other formats after testing concludes.

The subliminal_uialog_to_junit script, for example, parses the .plist into a JUnit report.

SLLogger (SLTest)

The methods in the SLLogger (SLTest) category are used by the tests to log test progress. They should not be called by a test writer.

See [SLTestTests testCompleteTestRunSequence] for an illustration of when these methods are called.

SLLogger (SLTestController)

The methods in the SLLogger (SLTestController) category are used by the shared test controller to log the progress of the test run. They should not be called by a test writer.

See [SLTestTests testCompleteTestRunSequence] for an illustration of when these methods are called.

Tasks

Getting and Setting the Shared Logger

  • + sharedLogger

    The shared logger used by the Subliminal framework and by user-defined tests.

Primitive Methods

Logging with Severity Levels

Logging Test Progress

Logging Run Progress

Class Methods

sharedLogger

The shared logger used by the Subliminal framework and by user-defined tests.

+ (SLLogger *)sharedLogger

Return Value

The shared logger.

Declared In

SLLogger.h

Instance Methods

currentQueueIsLoggingQueue

Whether or not the current queue is the loggingQueue.

- (BOOL)currentQueueIsLoggingQueue

Return Value

Whether or not the current queue is the loggingQueue.

Discussion

To avoid deadlocks, use this method to check if you’re on the loggingQueue before dispatch_syncing a block to it.

Declared In

SLLogger.h

logDebug:

Logs a message as a “debug” message.

- (void)logDebug:(NSString *)debug

Parameters

debug

The message to log.

Declared In

SLLogger.h

logError:

Logs a message as an “error” message.

- (void)logError:(NSString *)error

Parameters

error

The message to log.

Declared In

SLLogger.h

logException:expected:

Logs an exception thrown by a test.

- (void)logException:(NSException *)exception expected:(BOOL)expected

Parameters

exception

The exception to be logged.

expected

YES if the exception was “expected”, otherwise NO.

Discussion

The exception will be logged with call-site information if the exception’s userInfo dictionary contains both the SLLoggerExceptionFilenameKey and SLLoggerExceptionLineNumberKey keys.

See the discussion on the SLTest (SLTestCase) category for what constitutes an “expected” exception (in the context of a test failing due to this exception being raised).

Declared In

SLLogger.h

logMessage:

Logs a message.

- (void)logMessage:(NSString *)message

Parameters

message

The message to log.

Discussion

This method is the primitive logging method used by all other logging methods (by default) as well as by SLLog and SLLogAsync.

Declared In

SLLogger.h

logTest:caseFail:expected:

Logs that the specified test case has failed.

- (void)logTest:(NSString *)test caseFail:(NSString *)testCase expected:(BOOL)expected

Parameters

test

The test that is currently running.

testCase

The test case that has failed.

expected

YES if the failure was “expected”, otherwise NO.

Discussion

See the discussion on the SLTest (SLTestCase) category for what constitutes an “expected” failure.

Declared In

SLLogger.h

logTest:casePass:

Logs that the specified test case has passed.

- (void)logTest:(NSString *)test casePass:(NSString *)testCase

Parameters

test

The test that is currently running.

testCase

The test case that has passed.

Discussion

By not throwing any exceptions.

Declared In

SLLogger.h

logTest:caseStart:

Logs that the specified test case has started.

- (void)logTest:(NSString *)test caseStart:(NSString *)testCase

Parameters

test

The test that is currently running.

testCase

The test case that has started.

Declared In

SLLogger.h

logTestAbort:

Logs that the specified test has aborted.

- (void)logTestAbort:(NSString *)test

Parameters

test

The test that has aborted.

Discussion

As opposed to finishing; by throwing an exception in -setUpTest or -tearDownTest.

See Also

Declared In

SLLogger.h

logTestFinish:withNumCasesExecuted:numCasesFailed:numCasesFailedUnexpectedly:

Logs that the specified test has finished.

- (void)logTestFinish:(NSString *)test withNumCasesExecuted:(NSUInteger)numCasesExecuted numCasesFailed:(NSUInteger)numCasesFailed numCasesFailedUnexpectedly:(NSUInteger)numCasesFailedUnexpectedly

Parameters

test

The test that has finished.

numCasesExecuted

The number of cases that were executed.

numCasesFailed

Of numCasesExecuted, the number of cases that failed.

numCasesFailedUnexpectedly

Of numCasesFailed, the number of cases that failed unexpectedly (those test cases that failed for reasons other than test assertion failures).

Discussion

This means that it executed one or more test cases and did not throw an exception in -setUpTest or -tearDownTest.

See [SLTest runAndReportNumExecuted:failed:failedUnexpectedly:] for further discussion of the information that this method will be used to log.

See Also

Declared In

SLLogger.h

logTestStart:

Logs that the specified test has started.

- (void)logTestStart:(NSString *)test

Parameters

test

The test that has started.

Declared In

SLLogger.h

logTestingFinishWithNumTestsExecuted:numTestsFailed:

Logs that testing has finished.

- (void)logTestingFinishWithNumTestsExecuted:(NSUInteger)numTestsExecuted numTestsFailed:(NSUInteger)numTestsFailed

Parameters

numTestsExecuted

The number of tests that were executed.

numTestsFailed

Of numTestsExecuted, the number of tests that failed (by throwing an exception in set-up, tear-down, or a test case).

Discussion

This method is called after all tests have run.

Declared In

SLLogger.h

logTestingStart

Logs that testing has started.

- (void)logTestingStart

Discussion

This method is called before any tests have run.

Declared In

SLLogger.h

logUncaughtException:

Logs an exception that was not caught by the tests or application.

- (void)logUncaughtException:(NSException *)exception

Parameters

exception

The exception to be logged.

Discussion

This method is to be called from the test controller’s uncaught exception handler.

Declared In

SLLogger.h

logWarning:

Logs a message as a “warning” message.

- (void)logWarning:(NSString *)warning

Parameters

warning

The message to log.

Declared In

SLLogger.h

loggingQueue

Returns a queue on which log messages may be serialized.

- (dispatch_queue_t)loggingQueue

Return Value

A custom serial dispatch queue on which to serialize log messages.

Declared In

SLLogger.h