Expose Suite and Test objects for altercation

Fix for #872

As part of fixing #872 following was done :
* Introduced a new listener which when implemented
end users will be able to access both the XmlSuite
and the XmlTest inside it.
* Added tests.

5 files changed, 137 insertions, 11 deletions

diff --git a/src/main/java/org/testng/IAlterSuiteListener.java b/src/main/java/org/testng/IAlterSuiteListener.java
new file mode 100644
index 00000000..4c760a0e
--- /dev/null
+++ b/src/main/java/org/testng/IAlterSuiteListener.java
@@ -0,0 +1,25 @@
+package org.testng;
+
+import org.testng.xml.XmlSuite;
+
+import java.util.List;
+
+/**
+ * Implementations of this interface will gain access to the {@link XmlSuite} object and thus let users be able to
+ * alter a suite or a test based on their own needs.
+ * This listener can be added ONLY via the following two ways :
+ * <ol>
+ * <li>&lt;<code>listeners</code>&gt; tag in a suite file.</li>
+ * <li>via Service loaders</li>
+ * </ol>
+ * <p/>
+ * <b>Note: </b>This listener <b><u>will NOT be invoked</u></b> if it is wired in via the &#064;<code>Listeners</code>
+ * annotation.
+ */
+public interface IAlterSuiteListener extends ITestNGListener {
+    /**
+     * @param suites - The list of {@link XmlSuite}s that are part of the current execution.
+     */
+    void alter(List<XmlSuite> suites);
+
+}
diff --git a/src/main/java/org/testng/TestNG.java b/src/main/java/org/testng/TestNG.java
index 45cbab8f..1572bd57 100644
--- a/src/main/java/org/testng/TestNG.java
+++ b/src/main/java/org/testng/TestNG.java
@@ -185,6 +185,8 @@ public class TestNG {
 
   private List<IExecutionListener> m_executionListeners = Lists.newArrayList();
 
+  private List<IAlterSuiteListener> m_alterSuiteListeners= Lists.newArrayList();
+
   private boolean m_isInitialized = false;
 
   /**
@@ -735,6 +737,9 @@ public class TestNG {
       if (listener instanceof IConfigurationListener) {
         getConfiguration().addConfigurationListener((IConfigurationListener) listener);
       }
+      if (listener instanceof IAlterSuiteListener) {
+        addAlterSuiteListener((IAlterSuiteListener) listener);
+      }
     }
   }
 
@@ -1039,6 +1044,7 @@ public class TestNG {
 
     List<ISuite> suiteRunners = null;
 
+    runSuiteAlterationListeners();
     runExecutionListeners(true /* start */);
 
     m_start = System.currentTimeMillis();
@@ -1088,6 +1094,15 @@ public class TestNG {
     System.out.println("[TestNG] " + string);
   }
 
+  private void runSuiteAlterationListeners() {
+    for (List<IAlterSuiteListener> listeners
+        : Arrays.asList(m_alterSuiteListeners, m_configuration.getAlterSuiteListeners())) {
+      for (IAlterSuiteListener l : listeners) {
+        l.alter(m_suites);
+      }
+    }
+  }
+
   private void runExecutionListeners(boolean start) {
     for (List<IExecutionListener> listeners
         : Arrays.asList(m_executionListeners, m_configuration.getExecutionListeners())) {
@@ -1098,6 +1113,10 @@ public class TestNG {
     }
   }
 
+  public void addAlterSuiteListener(IAlterSuiteListener l) {
+    m_alterSuiteListeners.add(l);
+  }
+
   public void addExecutionListener(IExecutionListener l) {
     m_executionListeners.add(l);
   }
diff --git a/src/main/java/org/testng/internal/Configuration.java b/src/main/java/org/testng/internal/Configuration.java
index 46969325..e0fe87d2 100644
--- a/src/main/java/org/testng/internal/Configuration.java
+++ b/src/main/java/org/testng/internal/Configuration.java
@@ -1,10 +1,6 @@
 package org.testng.internal;
 
-import org.testng.IConfigurable;
-import org.testng.IConfigurationListener;
-import org.testng.IExecutionListener;
-import org.testng.IHookable;
-import org.testng.ITestObjectFactory;
+import org.testng.*;
 import org.testng.collections.Lists;
 import org.testng.internal.annotations.DefaultAnnotationTransformer;
 import org.testng.internal.annotations.IAnnotationFinder;
@@ -19,6 +15,7 @@ public class Configuration implements IConfiguration {
   IHookable m_hookable;
   IConfigurable m_configurable;
   List<IExecutionListener> m_executionListeners = Lists.newArrayList();
+  List<IAlterSuiteListener> m_alterSuiteListeners = Lists.newArrayList();
   private List<IConfigurationListener> m_configurationListeners = Lists.newArrayList();
 
   public Configuration() {
@@ -94,4 +91,10 @@ public class Configuration implements IConfiguration {
       m_configurationListeners.add(cl);
     }
   }
-}
\ No newline at end of file
+
+  @Override
+  public List<IAlterSuiteListener> getAlterSuiteListeners() {
+    return m_alterSuiteListeners;
+  }
+
+}
diff --git a/src/main/java/org/testng/internal/IConfiguration.java b/src/main/java/org/testng/internal/IConfiguration.java
index 2791b065..3d227b92 100644
--- a/src/main/java/org/testng/internal/IConfiguration.java
+++ b/src/main/java/org/testng/internal/IConfiguration.java
@@ -1,10 +1,6 @@
 package org.testng.internal;
 
-import org.testng.IConfigurable;
-import org.testng.IConfigurationListener;
-import org.testng.IExecutionListener;
-import org.testng.IHookable;
-import org.testng.ITestObjectFactory;
+import org.testng.*;
 import org.testng.internal.annotations.IAnnotationFinder;
 
 import java.util.List;
@@ -27,4 +23,6 @@ public interface IConfiguration {
 
   List<IConfigurationListener> getConfigurationListeners();
   void addConfigurationListener(IConfigurationListener cl);
+
+  List<IAlterSuiteListener> getAlterSuiteListeners();
 }
diff --git a/src/test/java/test/listeners/AlterSuiteListenerTest.java b/src/test/java/test/listeners/AlterSuiteListenerTest.java
new file mode 100644
index 00000000..438be8e7
--- /dev/null
+++ b/src/test/java/test/listeners/AlterSuiteListenerTest.java
@@ -0,0 +1,81 @@
+package test.listeners;
+
+import org.testng.Assert;
+import org.testng.IAlterSuiteListener;
+import org.testng.TestNG;
+import org.testng.annotations.Test;
+import org.testng.xml.XmlSuite;
+import org.testng.xml.XmlTest;
+import test.SimpleBaseTest;
+
+import java.util.Arrays;
+import java.util.List;
+
+public class AlterSuiteListenerTest extends SimpleBaseTest {
+
+    public static final String ALTER_SUITE_LISTENER = "AlterSuiteListener";
+
+    @Test
+    public void executionListenerWithXml() {
+        XmlSuite suite = runTest(AlterSuiteListener1SampleTest.class, AlterSuiteNameListener.class.getName());
+        Assert.assertEquals(suite.getName(), AlterSuiteNameListener.class.getSimpleName());
+    }
+
+    @Test
+    public void executionListenerWithoutListener() {
+        XmlSuite suite = runTest(AlterSuiteListener1SampleTest.class, null/*Donot add the listener*/);
+        Assert.assertEquals(suite.getName(), ALTER_SUITE_LISTENER);
+    }
+
+    @Test
+    public void executionListenerWithXml2() {
+        XmlSuite suite = runTest(AlterSuiteListener1SampleTest.class, AlterXmlTestsInSuiteListener.class.getName());
+        Assert.assertEquals(suite.getTests().size(), 2);
+    }
+
+
+    private XmlSuite runTest(Class<?> listenerClass, String listenerName) {
+        XmlSuite s = createXmlSuite(ALTER_SUITE_LISTENER);
+        createXmlTest(s, "Test", listenerClass.getName());
+        boolean addListener = (listenerName != null);
+
+        if (addListener) {
+            s.addListener(listenerName);
+        }
+        TestNG tng = create();
+        tng.setXmlSuites(Arrays.asList(s));
+        tng.run();
+        return s;
+    }
+
+    public static class AlterSuiteListener1SampleTest {
+        @Test
+        public void foo() {
+        }
+    }
+
+
+    public static class AlterSuiteNameListener implements IAlterSuiteListener {
+
+        @Override
+        public void alter(List<XmlSuite> suites) {
+            XmlSuite suite = suites.get(0);
+            suite.setName(getClass().getSimpleName());
+        }
+    }
+
+
+    public static class AlterXmlTestsInSuiteListener implements IAlterSuiteListener {
+
+        @Override
+        public void alter(List<XmlSuite> suites) {
+            XmlSuite suite = suites.get(0);
+            List<XmlTest> tests = suite.getTests();
+            XmlTest test = tests.get(0);
+            XmlTest anotherTest = new XmlTest(suite);
+            anotherTest.setName("foo");
+            anotherTest.setClasses(test.getClasses());
+        }
+    }
+
+}