Learning

Table of Contents

Basic Usage Overview

  1. Defining a TestPoint.
  2. Sending SLog statements.
  3. Capturing SLog statements.
  4. Creating a test script with visual tools.
  5. Creating test drivers.
  6. Automating test drivers and test scripts.
  7. Customizing tools for specific applications based on TestPoint data.

    8. Advanced Topics

  8. How to use Structured Log Testing to do Test Driven Development.
  9. Keeping track of log data and different application versions.
  10. Structured Log File (.slf) Specification




Material


1. Defining a TestPoint.

Defining TestPoints in code is one of the most critical exercises of Structured Log Testing. A TestPoint defines the critical unit of testable data. Choosing the TestPoint identifier and name value pairs is what the test scripts and tools use to check values over time. It might take practice to find the best values to define as TestPoints but luckily it doesn’t hurt to provide too much info and then filter later. You can create test scripts based on specific name value pairs within the TestPoint for a lot of flexibility in the testing process. The code to create a TestPoint is fairly straightforward, see the code below:

1
SLog.test(SomeClass, "MyTestPointId", {data1: classVariable1, data2: classVariable2});

The SLog.test() method has three parameters. The first parameter defines the category for this log statement and is used for filtering purposes. The second parameter is the TestPoint identifier and is used by tools to identify the test data. The third parameter defines the name value pair data set that is associated to the TestPoint. The tools then show the data names and default values that should be found and does comparison on the data set for testing validation (not necessarily pass or fail, with tools you can customize value ranges or other validation results).


2.  Sending SLog Statements

The first part of sending a log statement is to make a logging call. This is done with the SLog found in the Structured Log Testing SDK. The main class in the SDK is the SLog class. The below code shows SLog methods used to log statements:

1
2
3
4
5
6
7
// Basic logging methods
SLog.info(SomeClass, "Sending information");
SLog.debug(SomeClass, "Sending information with debug level");
SLog.warn(SomeClass, "Sending information with warn level");
SLog.fatal(SomeClass, "Sending information with fatal level");
// Structured Log Testing test method
SLog.test(SomeClass, "MyTestPoint", {data1: classVariable1, data2: classVariable2});

Making a call to the various log methods on the SLog class tells any registered logging targets that a statement wants to be sent out. The second part of sending log statements is registering logging targets to actually do something with the log statements. This two part ILogger and ILoggingTarget pattern comes from the Adobe Flex logging framework. The Structured Log Testing SDK has ported the guts of the Flex framework logging classes to work without any dependency to Flex framework classes. This allows for using Structured Log Testing SDK with non-Flex AS3 projects.


To register a ILoggingTarget to handle log statements you use the SLog.addTarget() method.

Alternatively in Flex, ILoggingTarget that are added to a MXML component will automatically register with SLog class. The target has to inherit the com.structuredlogs.targets.BaseTarget class or implement their on IMXMLObject.initialize() method implementing the target registeration.

The target classes actually do something with the log statements. They can send the statements in all kinds ways. The most common targets send messages to a local application, a remote database, or some in application component for display. In the Structured Log Testing SDK there are a few default logging targets that can be used as templates to create your own. The classes so far are:


StructuredLogTarget - Sends messages over Adobe Flash Player’s LocalConnection class using the “_slog” connection string.

TraceTarget - Sends messages to the Adobe Flash Player trace() method.

LogHistoryTarget - This target stores the messages in a local array and can be accessed by calling toString(). It spits out a string that is separated by the LogHistoryTarget.separator property.



Examples




3. Capturing SLog Statements

Now that your code is sending messages to various sources you need to be aware how to capture this data. As a developer the most common approach to capturing will be on your local machine with a tool that captures the data over LocalConnection. The Structured Log Testing project wants many applications to support the StructuredLogTarget or their own target with the LocalConnection connection string of “_slog”. The Structured Log Testing SDK has a helper class to create your own AIR (or Flex) application for capturing data over LocalConnection called SLogLocalConnection.


The SLogLocalConnection class is started or stopped by calling start() and stop() methods. Once an instance of the class has been created and started the LogEventHandler.UPDATE is where messages are received. Just setup a event handler and capture the messages. This code snippet comes from the BasicSLogViewerAIR example found in the code base.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"
    creationComplete="init()" xmlns:connection="com.structuredlogs.connection.*">
   
    <connection:SLogLocalConnection id="slogConn" update="updateHandler(event)" />
   
    <mx:Script>
        <![CDATA[
            import com.structuredlogs.data.StructuredLog;
            import com.structuredlogs.events.LogHandlerEvent;
           
            /**
             *  Display the latest logs on top.
             */
            private function updateHandler(event:LogHandlerEvent):void
            {
                var prefix:String = "[" + event.identifier + "]";
                for each(var log:StructuredLog in event.messages)
                {
                    var msg:String = log.getDisplayText(true, true);
                    txtOutput.text = prefix + msg + "\n" + txtOutput.text
                }
            }
           
            private function start():void
            {
                if (btnStart.selected)
                {
                    slogConn.start();
                    txtOutput.text += "START CONNECTION\n";
                }
                else
                {
                    slogConn.stop();
                    txtOutput.text += "STOP CONNECTION\n";
                }
            }
        ]]>
    </mx:Script>
    <mx:Button id="btnStart" label="{btnStart.selected ? 'Stop' : 'Start'}"
        toggle="true" click="start()" />
    <mx:TextArea id="txtOutput"
        top="22"
        width="100%" height="100%" />
</mx:WindowedApplication>



The BasicSLogViewerAIR is meant to demonstrate how to start building custom Structured Log Testing tools. See the list below for tools that currently support reading Structured Log Testing.


Tools using Structured Log Testing

  • RIALoggerApp - Renaun Erickson’s logging application which he uses to explore different logging ideas. Has tab/multiple identifiable logging windows, visual (*.slf) script creation and saving, and autoloading scripts with specific SLog statements.
  • REDBug - Coming soon.




4. Creating a test script with visual tools

Material being created…



5. Creating test drivers

In the Structured Log Testing approach a test driver is really any application that executes your code. The idea of a single test that is setup, executed, and then torn down doesn’t have to apply. You can create an application that runs through many aspects of the code and all the while have X number (overlapping or in sequence) test scripts being processed.

The Structured Log Testing SDK has two classes to help with loading scripts and do the testing. The first is the TestDriver that encapsulates load script and custom target implementation code. To create your own test runner you can use this class. The second class is an integration class into FlexUnit4. Since FlexUnit4 provides a lot of other testing framework gut code that doesn’t need to be reinvented. This custom FlexUnit4 IRunner class is called SLogTestRunner. A test class that wants to run in a FlexUnit4 ITestRunner class looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
package unittest
{
import classes.Discounter;

import com.structuredlogs.runners.SLogTestRunner;

import flash.events.Event;
import flash.events.TimerEvent;
import flash.utils.Timer;

import org.flexunit.Assert;
import org.flexunit.async.Async;
   

[RunWith("com.structuredlogs.runners.SLogTestRunner")]
public class TestDiscountBin
{  
    private var runner:SLogTestRunner;
   
    [SLF]
    public static var promo1:String = "unittest/scripts/demo.slf";
   
    [TestDriver]
    public function goneShopping():void
    {      
       
        SLog.testActivateScript("demo", true);
        var discount:Discounter = new Discounter(80.00);
        discount.applyPromo("DIS10");
        discount.calculatePrice();
        SLog.testActivateScript("demo", false);
    }
   
}
}

This custom IRunner class defines its own metadata requirements. The two required metadata tags are [SLT] and [TestDriver]. The [SLT] metadata tag defines the TestPointScript that will be loaded and used, so the value is a path to the file on your local machine (should be able to support loading the scripts from a url in the future). The second [TestDriver] metadata is defined on one and only one method in the test class. This method is the one method that runs code that will generate logs used to compare with the loaded scripts.



6. Automating test drivers and test scripts

There are different approaches to automating test drivers and test scripts. The Structured Log Testing SDK provides means to embed or load at runtime Test Script in the Structured Log File (.slf) file format. Then there are classes in the Structured Log Testing SDK to support reporting of the test results.

Any automation systems that support running Flash SWF’s will work with the running the test drivers and test scripts written for Structured Log Testing.


With the integration with FlexUnit4 you get all the benefits of that frameworks Continuous Integration hooks or automation test runners.



7. Customizing tools for specific applications based on TestPoint data

Material being created…


SetPageWidth