Step 1: Download Surrogate

The various Surrogate distributions can be downloaded from the SourceForge Surrogate Download home page.

The surrogate-core distribution contains the Surrogate core jar and the API documentation.

The surrogate-example contains example testclasses, aspects, build scripts and third-party jars necessary for building the examples. This also includes the AspectJ aspectjtools.jar and aspectjrt.jar

Download both distributions and unzip/untar under a common parent directory on your hard-drive, e.g. C:\surrogate.

Step 2: Preparing Ant

It is assumed that you already have Ant installed. It can be downloaded from apache.org

1. If you don't have JUnit installed, copy junit.jar from the surrogate-example/lib folder to your $ANT_HOME/lib directory.
2. If you don't have AspectJ installed, copy aspectjtools.jars from the surrogate-example/lib folder to your $ANT_HOME/lib directory.

As a test, you should now be able to build and run the test in the surrogate-example folder by

          ant -Dsurrogate.debug=true 
       

Step 3: Enabling Surrogate in existing build.xml

Copy the surrogate.jar, mockobjects-core.jar and aspectjrt.jar to your projects lib folder.

The build_quickstart.xml Ant script contains an example of how to set up your project to switch between Surrogate and "normal" build. I.e set the following in your project's init target:

    
    <target name="init">
        <property name="SOURCE_DIR" value="src/java" />
        <property name="TESTSOURCE_DIR" value="src/test" />
        <property name="ASPECTSOURCE_DIR" value="src/aspects" />             
        <!-- surrogate.jar, mockobjects.jar and aspectjrt.jar must be in "lib" -->
        <!-- aspectjtools.jar must be in $ANT_HOME/lib -->
        <path id="compile.path">
            <fileset dir="lib">
                <include name="*.jar"/>
            </fileset>
        </path>
    </target>
    

Add the following compilerargs to your projects compile target:

   
    <!-- Switches compiler and "classes" dir if -Dsurrogate=true -->
    <target name="init.surrogate" if="surrogate">
        <property name="AJC" value="org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter"/>    
        <property name="build.compiler" value="${AJC}"/>
        <property name="CLASSES_DIR" value="woven-classes"/>
    </target>
     <target name="noinit.surrogate" unless="surrogate">
         <property name="CLASSES_DIR" value="classes"/>
    </target>
    <target name="check.surrogate" depends="init.surrogate,noinit.surrogate"/>
    
    <!-- Compile target -->
    <target name="compile" depends="init,check.surrogate" description="compiles">
        <mkdir dir="${CLASSES_DIR}"/> 
        <javac srcdir="${SOURCE_DIR}" destdir="${CLASSES_DIR}"  debug="on" >
            <classpath>
                <path refid="compile.path"/>
            </classpath>
            <compilerarg compiler="${AJC}" line="-Xreweavable"/>
            <compilerarg compiler="${AJC}" line="-Xsrcdir ${ASPECTSOURCE_DIR}"/>
        </javac>
    </target>
    

Step 4: Create the project Surrogate aspect

Create the file MySurrogateCalls.java in the src/aspects folder and insert the following:

   
   import net.sf.surrogate.core.SurrogateCalls;
   aspect MySurrogateCalls extends SurrogateCalls {
   protected pointcut mockPointcut() :
       (
           call (java.io.*Reader.new(..)) ||
           call(* java.lang.System.currentTimeMillis())
        );
   }
   

Step 5: Running your Unit Tests with and without Surrogate

Assuming that you already have a clean and test target, compile and run the tests with:

       ant  clean test  (runs without Surrogate)
       ant  -Dsurrogate=true -Dsurrogate.debug=true clean test  (runs with Surrogate)
    

In the last run, Surrogate will report possible calls where you can insert a mock, e.g. all calls to System.currentTimeMillis or creation of java.io.Reader objects.

Step 6: Start using mocks objects!

The Surrogate User Guide describes how to start injecting mock objects and mock methods.