SONAR-7612 Improve documentation and SensorContextTester

plugins/sonar-xoo-plugin/src/test/java/org/sonar/xoo/lang/CpdTokenizerSensorTest.java

@@ -21,7 +21,6 @@ package org.sonar.xoo.lang;
 
 import java.io.File;
 import java.io.IOException;
-import java.io.StringReader;
 import org.apache.commons.io.FileUtils;
 import org.junit.Before;
 import org.junit.Rule;
@@ -29,7 +28,6 @@ import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.junit.rules.TemporaryFolder;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.sensor.internal.DefaultSensorDescriptor;
 import org.sonar.api.batch.sensor.internal.SensorContextTester;
 
@@ -80,7 +78,7 @@ public class CpdTokenizerSensorTest {
     FileUtils.write(sourceFile, content);
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/foo.xoo")
       .setLanguage("xoo")
-      .initMetadata(new FileMetadata().readMetadata(new StringReader(content)));
+      .initMetadata(content);
     context.fileSystem().add(inputFile);
   }
 

plugins/sonar-xoo-plugin/src/test/java/org/sonar/xoo/lang/SyntaxHighlightingSensorTest.java

@@ -19,21 +19,18 @@
  */
 package org.sonar.xoo.lang;
 
+import java.io.File;
+import java.io.IOException;
 import org.apache.commons.io.FileUtils;
 import org.junit.Before;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.TemporaryFolder;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.sensor.highlighting.TypeOfText;
 import org.sonar.api.batch.sensor.internal.DefaultSensorDescriptor;
 import org.sonar.api.batch.sensor.internal.SensorContextTester;
 
-import java.io.File;
-import java.io.IOException;
-import java.io.StringReader;
-
 import static org.assertj.core.api.Assertions.assertThat;
 
 public class SyntaxHighlightingSensorTest {
@@ -69,7 +66,7 @@ public class SyntaxHighlightingSensorTest {
     File symbol = new File(baseDir, "src/foo.xoo.highlighting");
     FileUtils.write(symbol, "1:4:k\n12:15:cppd\n\n#comment");
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/foo.xoo").setLanguage("xoo")
-      .initMetadata(new FileMetadata().readMetadata(new StringReader(" xoo\nazertyazer\nfoo")));
+      .initMetadata(" xoo\nazertyazer\nfoo");
     context.fileSystem().add(inputFile);
 
     sensor.execute(context);

plugins/sonar-xoo-plugin/src/test/java/org/sonar/xoo/rule/OneIssuePerLineSensorTest.java

@@ -20,12 +20,10 @@
 package org.sonar.xoo.rule;
 
 import java.io.IOException;
-import java.io.StringReader;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.TemporaryFolder;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.rule.Severity;
 import org.sonar.api.batch.sensor.internal.DefaultSensorDescriptor;
 import org.sonar.api.batch.sensor.internal.SensorContextTester;
@@ -52,7 +50,7 @@ public class OneIssuePerLineSensorTest {
   @Test
   public void testRule() throws IOException {
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.xoo").setLanguage(Xoo.KEY)
-      .initMetadata(new FileMetadata().readMetadata(new StringReader("a\nb\nc\nd\ne\nf\ng\nh\ni\n")));
+      .initMetadata("a\nb\nc\nd\ne\nf\ng\nh\ni\n");
 
     SensorContextTester context = SensorContextTester.create(temp.newFolder());
     context.fileSystem().add(inputFile);
@@ -67,7 +65,7 @@ public class OneIssuePerLineSensorTest {
   @Test
   public void testForceSeverity() throws IOException {
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.xoo").setLanguage(Xoo.KEY)
-      .initMetadata(new FileMetadata().readMetadata(new StringReader("a\nb\nc\nd\ne\nf\ng\nh\ni\n")));
+      .initMetadata("a\nb\nc\nd\ne\nf\ng\nh\ni\n");
 
     SensorContextTester context = SensorContextTester.create(temp.newFolder());
     context.fileSystem().add(inputFile);
@@ -84,7 +82,7 @@ public class OneIssuePerLineSensorTest {
   @Test
   public void testProvideGap() throws IOException {
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.xoo").setLanguage(Xoo.KEY)
-      .initMetadata(new FileMetadata().readMetadata(new StringReader("a\nb\nc\nd\ne\nf\ng\nh\ni\n")));
+      .initMetadata("a\nb\nc\nd\ne\nf\ng\nh\ni\n");
 
     SensorContextTester context = SensorContextTester.create(temp.newFolder());
     context.fileSystem().add(inputFile);
@@ -101,7 +99,7 @@ public class OneIssuePerLineSensorTest {
   @Test
   public void testProvideGap_before_5_5() throws IOException {
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.xoo").setLanguage(Xoo.KEY)
-      .initMetadata(new FileMetadata().readMetadata(new StringReader("a\nb\nc\nd\ne\nf\ng\nh\ni\n")));
+      .initMetadata("a\nb\nc\nd\ne\nf\ng\nh\ni\n");
 
     SensorContextTester context = SensorContextTester.create(temp.newFolder());
     context.fileSystem().add(inputFile);

sonar-plugin-api/src/main/java/org/sonar/api/batch/fs/internal/DefaultInputFile.java

@@ -25,6 +25,7 @@ import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.InputStream;
+import java.io.StringReader;
 import java.nio.charset.Charset;
 import java.nio.file.Path;
 import java.util.Arrays;
@@ -287,6 +288,13 @@ public class DefaultInputFile extends DefaultInputComponent implements InputFile
     return this;
   }
 
+  /**
+   * For testing purpose
+   */
+  public DefaultInputFile initMetadata(String content) {
+    return initMetadata(new FileMetadata().readMetadata(new StringReader(content)));
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) {

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/Sensor.java

@@ -21,6 +21,7 @@ package org.sonar.api.batch.sensor;
 
 import org.sonar.api.ExtensionPoint;
 import org.sonar.api.batch.BatchSide;
+import org.sonar.api.batch.sensor.internal.SensorContextTester;
 
 /**
  * <p>
@@ -28,6 +29,8 @@ import org.sonar.api.batch.BatchSide;
  * used to add measure and issues at file level.
  * <p>
  * For example the Cobertura Sensor parses Cobertura report and saves the first-level of measures on files.
+ * 
+ * For testing purpose you can use {@link SensorContextTester}
  * @since 5.1
  */
 @BatchSide

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/coverage/NewCoverage.java

@@ -23,6 +23,22 @@ import org.sonar.api.batch.fs.InputFile;
 
 /**
  * This builder is used to define code coverage by tests of a given type (UT/IT/Overall) on files.
+ * 
+ * Example:
+ * 
+ * <pre>
+ *   sensorContext.newCoverage().onFile(file)
+       .ofType(UNIT)
+       .lineHits(1, 2)
+       .lineHits(2, 5)
+       .lineHits(3, 0)
+       . ...
+       .conditions(3, 4, 2)
+       .conditions(12, 2, 2)
+       . ...
+       .save();
+ *     
+ * </pre>
  * @since 5.2
  */
 public interface NewCoverage {

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cpd/NewCpdTokens.java

@@ -24,6 +24,17 @@ import org.sonar.api.batch.fs.TextRange;
 
 /**
  * This builder is used to define tokens used by CPD algorithm on files.
+ * 
+ * Example:
+ * 
+ * <pre>
+ *   sensorContext.newCpdTokens().onFile(inputFile)
+ *     .addToken(1, 10, 1, 15, "class")
+ *     .addToken(1, 16, 1, 18, "IDENTIFIER")
+ *     // Add more tokens
+ *     .save;
+ *     
+ * </pre>
  * @since 5.5
  */
 public interface NewCpdTokens {
@@ -40,6 +51,12 @@ public interface NewCpdTokens {
    */
   NewCpdTokens addToken(TextRange range, String image);
 
+  /**
+   * Shortcut to avoid calling {@link InputFile#newRange(int, int, int, int)}
+   * @since 5.6
+   */
+  NewCpdTokens addToken(int startLine, int startLineOffset, int endLine, int endLineOffset, String image);
+
   /**
    * Call this method only once when your are done with defining tokens of the file.
    */

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/cpd/internal/DefaultCpdTokens.java

@@ -80,11 +80,23 @@ public class DefaultCpdTokens extends DefaultStorable implements NewCpdTokens {
     return inputFile;
   }
 
+  @Override
+  public NewCpdTokens addToken(int startLine, int startLineOffset, int endLine, int endLineOffset, String image) {
+    checkInputFileNotNull();
+    TextRange newRange;
+    try {
+      newRange = inputFile.newRange(startLine, startLineOffset, endLine, endLineOffset);
+    } catch (Exception e) {
+      throw new IllegalArgumentException("Unable to register token in file " + inputFile, e);
+    }
+    return addToken(newRange, image);
+  }
+
   @Override
   public DefaultCpdTokens addToken(TextRange range, String image) {
     Preconditions.checkNotNull(range, "Range should not be null");
     Preconditions.checkNotNull(image, "Image should not be null");
-    Preconditions.checkState(inputFile != null, "Call onFile() first");
+    checkInputFileNotNull();
     if (excluded) {
       return this;
     }
@@ -126,4 +138,8 @@ public class DefaultCpdTokens extends DefaultStorable implements NewCpdTokens {
     addNewTokensLine(result, startIndex, currentIndex, startLine, sb);
     storage.store(this);
   }
+
+  private void checkInputFileNotNull() {
+    Preconditions.checkState(inputFile != null, "Call onFile() first");
+  }
 }

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/highlighting/NewHighlighting.java

@@ -24,6 +24,18 @@ import org.sonar.api.batch.fs.TextRange;
 
 /**
  * This builder is used to define syntax highlighting (aka code coloration) on files.
+ * 
+ * Example:
+ * 
+ * <pre>
+ *   sensorContext.newHighlighting().onFile(inputFile)
+ *     .highlight(1, 10, 1, 15, KEYWORD)
+ *     .highlight(1, 16, 1, 18, STRING)
+ *     // Add more highlight if needed
+ *     .save;
+ *     
+ * </pre>
+ * 
  * @since 5.1
  */
 public interface NewHighlighting {

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/internal/SensorContextTester.java

@@ -67,8 +67,16 @@ import org.sonar.duplications.internal.pmd.TokensLine;
 /**
  * Utility class to help testing {@link Sensor}.
  * 
- * Usage: call {@link #create(File)} to create an "in memory" implementation of {@link SensorContext} then
- * pass it to your {@link Sensor}. You can then query elements provided by your sensor using methods {@link #allIssues()}, ...
+ * Usage: call {@link #create(File)} to create an "in memory" implementation of {@link SensorContext} with a filesystem initialized with provided baseDir.
+ * <p>
+ * You have to manually register inputFiles using:
+ * <pre>
+ *   sensorContextTester.fileSystem().add(new DefaultInputFile("myProjectKey", "src/Foo.java")
+      .setLanguage("java")
+      .initMetadata("public class Foo {\n}"));
+ * </pre>
+ * <p>
+ * Then pass it to your {@link Sensor}. You can then query elements provided by your sensor using methods {@link #allIssues()}, ...
  * 
  * @since 5.1
  */

sonar-plugin-api/src/main/java/org/sonar/api/batch/sensor/symbol/NewSymbolTable.java

@@ -24,6 +24,21 @@ import org.sonar.api.batch.fs.TextRange;
 
 /**
  * This builder is used to define symbol references on files.
+ * 
+ * Example:
+ * 
+ * <pre>
+ *   NewSymbolTable symbolTable = sensorContext.newSymbolTable().onFile(inputFile);
+ *   symbolTable.newSymbol(1, 10, 1, 15)
+ *     .newReference(10, 12, 10, 17)
+ *     .newReference(11, 11, 11, 16);
+ *     
+ *   // Add more symbols if needed
+ *     
+ *   symbolTable.save();
+ *     
+ * </pre>
+ * 
  * @since 5.6
  */
 public interface NewSymbolTable {

sonar-scanner-engine/src/main/java/org/sonar/batch/sensor/noop/NoOpNewCpdTokens.java

@@ -40,4 +40,10 @@ public class NoOpNewCpdTokens implements NewCpdTokens {
     // Do nothing
     return this;
   }
+
+  @Override
+  public NewCpdTokens addToken(int startLine, int startLineOffset, int endLine, int endLineOffset, String image) {
+    // Do nothing
+    return this;
+  }
 }

sonar-scanner-engine/src/test/java/org/sonar/batch/issue/ModuleIssuesTest.java

@@ -19,7 +19,6 @@
  */
 package org.sonar.batch.issue;
 
-import java.io.StringReader;
 import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -28,7 +27,6 @@ import org.mockito.Mock;
 import org.mockito.runners.MockitoJUnitRunner;
 import org.sonar.api.batch.fs.InputFile;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.rule.internal.ActiveRulesBuilder;
 import org.sonar.api.batch.rule.internal.RulesBuilder;
 import org.sonar.api.batch.sensor.issue.internal.DefaultIssue;
@@ -67,7 +65,7 @@ public class ModuleIssuesTest {
   ModuleIssues moduleIssues;
 
   BatchComponentCache componentCache = new BatchComponentCache();
-  InputFile file = new DefaultInputFile("foo", "src/Foo.php").initMetadata(new FileMetadata().readMetadata(new StringReader("Foo\nBar\nBiz\n")));
+  InputFile file = new DefaultInputFile("foo", "src/Foo.php").initMetadata("Foo\nBar\nBiz\n");
   ReportPublisher reportPublisher = mock(ReportPublisher.class, RETURNS_DEEP_STUBS);
 
   @Before

sonar-scanner-engine/src/test/java/org/sonar/batch/source/DefaultHighlightableTest.java

@@ -19,14 +19,12 @@
  */
 package org.sonar.batch.source;
 
-import java.io.StringReader;
 import org.junit.Rule;
 import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.mockito.ArgumentCaptor;
 import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.sensor.highlighting.internal.DefaultHighlighting;
 import org.sonar.api.batch.sensor.internal.SensorStorage;
 
@@ -43,7 +41,7 @@ public class DefaultHighlightableTest {
   public void should_store_highlighting_rules() {
     SensorStorage sensorStorage = mock(SensorStorage.class);
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.php")
-      .initMetadata(new FileMetadata().readMetadata(new StringReader("azerty\nbla bla")));
+      .initMetadata("azerty\nbla bla");
     DefaultHighlightable highlightablePerspective = new DefaultHighlightable(inputFile, sensorStorage, mock(AnalysisMode.class));
     highlightablePerspective.newHighlighting().highlight(0, 6, "k").highlight(7, 10, "cppd").done();
 

sonar-scanner-engine/src/test/java/org/sonar/batch/source/DefaultSymbolizableTest.java

@@ -20,12 +20,10 @@
 package org.sonar.batch.source;
 
 import com.google.common.base.Strings;
-import java.io.StringReader;
 import org.junit.Test;
 import org.mockito.ArgumentCaptor;
 import org.sonar.api.batch.AnalysisMode;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.sensor.symbol.internal.DefaultSymbolTable;
 import org.sonar.api.source.Symbol;
 import org.sonar.api.source.Symbolizable;
@@ -42,7 +40,7 @@ public class DefaultSymbolizableTest {
 
     DefaultSensorStorage sensorStorage = mock(DefaultSensorStorage.class);
     DefaultInputFile inputFile = new DefaultInputFile("foo", "src/Foo.php")
-      .initMetadata(new FileMetadata().readMetadata(new StringReader(Strings.repeat("azerty\n", 20))));
+      .initMetadata(Strings.repeat("azerty\n", 20));
 
     DefaultSymbolizable symbolPerspective = new DefaultSymbolizable(inputFile, sensorStorage, mock(AnalysisMode.class));
     Symbolizable.SymbolTableBuilder symbolTableBuilder = symbolPerspective.newSymbolTableBuilder();

sonar-scanner-engine/src/test/java/org/sonar/batch/source/DeprecatedDefaultSymbolTableTest.java

@@ -20,7 +20,6 @@
 package org.sonar.batch.source;
 
 import com.google.common.base.Strings;
-import java.io.StringReader;
 import java.util.Set;
 import org.junit.Before;
 import org.junit.Rule;
@@ -28,7 +27,6 @@ import org.junit.Test;
 import org.junit.rules.ExpectedException;
 import org.sonar.api.batch.fs.TextRange;
 import org.sonar.api.batch.fs.internal.DefaultInputFile;
-import org.sonar.api.batch.fs.internal.FileMetadata;
 import org.sonar.api.batch.sensor.symbol.internal.DefaultSymbolTable;
 import org.sonar.api.source.Symbol;
 import org.sonar.api.source.Symbolizable;
@@ -44,7 +42,7 @@ public class DeprecatedDefaultSymbolTableTest {
   @Before
   public void prepare() {
     inputFile = new DefaultInputFile("foo", "src/Foo.php")
-      .initMetadata(new FileMetadata().readMetadata(new StringReader(Strings.repeat("azerty\n", 20))));
+      .initMetadata(Strings.repeat("azerty\n", 20));
   }
 
   @Test