From 1d278221a709d2a26c73e76c4aeed1ba003fa6f3 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Fri, 1 Mar 2013 14:41:12 -0600 Subject: more documentation --- src/main/scala/org/perl8/test/Test.scala | 12 +++++++++--- .../scala/org/perl8/test/harness/MultiTestReporter.scala | 11 +++++++++++ src/main/scala/org/perl8/test/harness/Reporter.scala | 10 ++++++++++ src/main/scala/org/perl8/test/harness/SummarizedTests.scala | 12 +++++++++++- src/main/scala/org/perl8/test/harness/SummaryReporter.scala | 8 ++++++-- src/main/scala/org/perl8/test/harness/TAPReporter.scala | 3 +++ src/main/scala/org/perl8/test/harness/package.scala | 13 +++++++++++++ src/main/scala/org/perl8/test/sbt/Fingerprint.scala | 3 +++ src/main/scala/org/perl8/test/sbt/Framework.scala | 3 +++ src/main/scala/org/perl8/test/sbt/Runner.scala | 4 ++++ src/main/scala/org/perl8/test/sbt/SBTReporter.scala | 2 ++ src/main/scala/org/perl8/test/sbt/package.scala | 5 +++++ src/main/scala/org/perl8/test/tap/package.scala | 5 +++++ 13 files changed, 85 insertions(+), 6 deletions(-) create mode 100644 src/main/scala/org/perl8/test/sbt/package.scala (limited to 'src') diff --git a/src/main/scala/org/perl8/test/Test.scala b/src/main/scala/org/perl8/test/Test.scala index 436719c..ffe75b9 100644 --- a/src/main/scala/org/perl8/test/Test.scala +++ b/src/main/scala/org/perl8/test/Test.scala @@ -7,6 +7,12 @@ package org.perl8.test trait Test { /** Runs the test. The TAP stream will be written to Console.out and * Console.err, so you can swap these out as required in order to parse it. + * + * @return The exit code that the test produced. Success is indicated by 0, + * failure to run the correct number of tests by 255, and any other + * failure by the number of tests that failed. This should be used + * by reporters which run a single test, which can call + * `sys.exit(exitCode)` */ def run: Int = runTests(false) @@ -16,9 +22,9 @@ trait Test { * * Summarizing test reporters tend to repeatedly update the same line on * the terminal, so this method makes calls to - * [[tap.TestBuilder#diag diag]] (which sends messages to stderr, where - * they are typically displayed as-is) prefix the message with a newline, - * to ensure that the output starts on its own line. + * [[org.perl8.test.tap.TestBuilder#diag diag]] (which sends messages to + * stderr, where they are typically displayed as-is) prefix the message + * with a newline, to ensure that the output starts on its own line. */ def runInHarness: Int = runTests(true) diff --git a/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala b/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala index b0548e4..8d50528 100644 --- a/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala +++ b/src/main/scala/org/perl8/test/harness/MultiTestReporter.scala @@ -1,5 +1,16 @@ package org.perl8.test.harness +/** Classes that implement `MultiTestReporter` are capable of running a group + * of test classes, given their names. This typically involves some sort of + * summarization. + * + * See also: [[org.perl8.test.harness.MultiTestReporter]]. + */ trait MultiTestReporter { + /** Runs the test classes identifed by the list of fully qualified class + * names `testNames`. + * + * @return The exit code for the harness to use. Will be 0 on success. + */ def run (testNames: Seq[String]): Int } diff --git a/src/main/scala/org/perl8/test/harness/Reporter.scala b/src/main/scala/org/perl8/test/harness/Reporter.scala index 536636f..749cb30 100644 --- a/src/main/scala/org/perl8/test/harness/Reporter.scala +++ b/src/main/scala/org/perl8/test/harness/Reporter.scala @@ -1,5 +1,15 @@ package org.perl8.test.harness +/** Classes that implement `Reporter` are capable of running a test class, + * given its name. + * + * See also: [[org.perl8.test.harness.MultiTestReporter]]. + */ trait Reporter { + /** Runs the test class identifed by the fully qualified class name + * `testName`. + * + * @return The exit code for the harness to use. Will be 0 on success. + */ def run (testName: String): Int } diff --git a/src/main/scala/org/perl8/test/harness/SummarizedTests.scala b/src/main/scala/org/perl8/test/harness/SummarizedTests.scala index 3688011..207cc18 100644 --- a/src/main/scala/org/perl8/test/harness/SummarizedTests.scala +++ b/src/main/scala/org/perl8/test/harness/SummarizedTests.scala @@ -9,8 +9,18 @@ import scala.concurrent.Future import org.perl8.test.tap.{Parser,TAPEvent,TAPResult,TodoDirective} import org.perl8.test.Test +/** This is a trait for classes that run tests and summarize the results. It + * provides a single `runOneTest` method, which runs a test class and + * produces a stream of [[org.perl8.test.tap.TAPEvent TAP events]] which can + * be used to produce whatever summarized output you need. + */ trait SummarizedTests { - def runOneTest (test: Test, cb: TAPEvent => Unit): TAPResult = { + /** Runs a single [[org.perl8.test.Test test]] instance, calling `cb` with + * each [[org.perl8.test.tap.TAPEvent TAP event]] as it is produced. + * + * @return The overall result of the test instance. + */ + protected def runOneTest (test: Test, cb: TAPEvent => Unit): TAPResult = { val out = new PipedOutputStream val in = new PipedInputStream(out) diff --git a/src/main/scala/org/perl8/test/harness/SummaryReporter.scala b/src/main/scala/org/perl8/test/harness/SummaryReporter.scala index 083290b..1901bcf 100644 --- a/src/main/scala/org/perl8/test/harness/SummaryReporter.scala +++ b/src/main/scala/org/perl8/test/harness/SummaryReporter.scala @@ -4,6 +4,10 @@ import org.perl8.test.tap.{TAPEvent,StartEvent,ResultEvent,PlanEvent,EndEvent} import org.perl8.test.tap.{TAPResult,TodoDirective} import org.perl8.test.Test +/** Runs a series of tests. The TAP output from these tests is parsed, and + * output is produced which is similar in style to Perl's + * [[https://metacpan.org/module/Test::Harness Test::Harness]]. + */ class SummaryReporter extends MultiTestReporter with SummarizedTests { def run (testNames: Seq[String]): Int = { val results = runTests(testNames) @@ -12,7 +16,7 @@ class SummaryReporter extends MultiTestReporter with SummarizedTests { if (success) 0 else 1 } - def runTests (testNames: Seq[String]): Map[String, TAPResult] = { + protected def runTests (testNames: Seq[String]): Map[String, TAPResult] = { val maxLength = testNames.map(_.length).max testNames.map { name => @@ -70,7 +74,7 @@ class SummaryReporter extends MultiTestReporter with SummarizedTests { }.toMap } - def printTestSummary ( + protected def printTestSummary ( success: Boolean, results: Map[String, TAPResult] ) { diff --git a/src/main/scala/org/perl8/test/harness/TAPReporter.scala b/src/main/scala/org/perl8/test/harness/TAPReporter.scala index 47a88c5..58dd175 100644 --- a/src/main/scala/org/perl8/test/harness/TAPReporter.scala +++ b/src/main/scala/org/perl8/test/harness/TAPReporter.scala @@ -3,6 +3,9 @@ package org.perl8.test.harness import org.perl8.test.tap import org.perl8.test.Test +/** Runs a single test. The TAP stream from that test is written directly to + * stdout/stderr. + */ class TAPReporter extends Reporter { def run (testName: String): Int = newInstance[Test](testName).run diff --git a/src/main/scala/org/perl8/test/harness/package.scala b/src/main/scala/org/perl8/test/harness/package.scala index a5641e8..fbebf07 100644 --- a/src/main/scala/org/perl8/test/harness/package.scala +++ b/src/main/scala/org/perl8/test/harness/package.scala @@ -1,14 +1,27 @@ package org.perl8.test +/** Classes to handle running test instances and providing output. + */ package object harness { import scala.reflect.{ClassTag,classTag} + /** Loads `className`, returning the + * [[http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html java.lang.Class]] + * instance. + */ def loadClass[T: ClassTag] (className: String): Class[_] = classTag[T].runtimeClass.getClassLoader.loadClass(className) + /** Loads `className` and creates a new instance of it, using the + * no-argument constructor. + */ def newInstance[T: ClassTag] (className: String): T = loadClass[T](className).newInstance.asInstanceOf[T] + /** Loads `className` and creates a new instance of it, using a + * one-argument constructor. Passes `arg` as the argument to the + * constructor. + */ def newInstance[T: ClassTag, U <: AnyRef: ClassTag] ( className: String, arg: U diff --git a/src/main/scala/org/perl8/test/sbt/Fingerprint.scala b/src/main/scala/org/perl8/test/sbt/Fingerprint.scala index 9cea6f1..c60c97b 100644 --- a/src/main/scala/org/perl8/test/sbt/Fingerprint.scala +++ b/src/main/scala/org/perl8/test/sbt/Fingerprint.scala @@ -2,6 +2,9 @@ package org.perl8.test.sbt import org.scalatools.testing +/** Implementation of + * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Fingerprint.java org.scalatools.testing.Fingerprint]]. + */ object Fingerprint extends testing.SubclassFingerprint { def isModule: Boolean = false def superClassName: String = "org.perl8.test.Test" diff --git a/src/main/scala/org/perl8/test/sbt/Framework.scala b/src/main/scala/org/perl8/test/sbt/Framework.scala index 74ea6d8..e8b5c57 100644 --- a/src/main/scala/org/perl8/test/sbt/Framework.scala +++ b/src/main/scala/org/perl8/test/sbt/Framework.scala @@ -2,6 +2,9 @@ package org.perl8.test.sbt import org.scalatools.testing +/** Implementation of + * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Framework.java org.scalatools.testing.Framework]]. + */ class Framework extends testing.Framework { val name: String = "Perl8 Test" val tests: Array[testing.Fingerprint] = Array(Fingerprint) diff --git a/src/main/scala/org/perl8/test/sbt/Runner.scala b/src/main/scala/org/perl8/test/sbt/Runner.scala index f403b32..442e4eb 100644 --- a/src/main/scala/org/perl8/test/sbt/Runner.scala +++ b/src/main/scala/org/perl8/test/sbt/Runner.scala @@ -5,6 +5,10 @@ import org.scalatools.testing import org.perl8.test.harness.SummaryReporter import org.perl8.test.Test +/** Implementation of + * [[http://github.com/harrah/test-interface/blob/master/src/org/scalatools/testing/Runner2.java org.scalatools.testing.Runner2]] + * using [[org.perl8.test.sbt.SBTReporter SBTReporter]]. + */ class Runner ( loader: ClassLoader, loggers: Array[testing.Logger] diff --git a/src/main/scala/org/perl8/test/sbt/SBTReporter.scala b/src/main/scala/org/perl8/test/sbt/SBTReporter.scala index 148c380..5277904 100644 --- a/src/main/scala/org/perl8/test/sbt/SBTReporter.scala +++ b/src/main/scala/org/perl8/test/sbt/SBTReporter.scala @@ -6,6 +6,8 @@ import org.perl8.test.harness.{Reporter,SummarizedTests} import org.perl8.test.tap.{TAPEvent,ResultEvent,EndEvent} import org.perl8.test.Test +/** Runs a single test under the SBT test harness. + */ class SBTReporter ( loader: ClassLoader, loggers: Array[testing.Logger], diff --git a/src/main/scala/org/perl8/test/sbt/package.scala b/src/main/scala/org/perl8/test/sbt/package.scala new file mode 100644 index 0000000..ce3652a --- /dev/null +++ b/src/main/scala/org/perl8/test/sbt/package.scala @@ -0,0 +1,5 @@ +package org.perl8.test + +/** Classes for interoperating with `sbt test`. + */ +package object sbt diff --git a/src/main/scala/org/perl8/test/tap/package.scala b/src/main/scala/org/perl8/test/tap/package.scala index ffc732c..434497d 100644 --- a/src/main/scala/org/perl8/test/tap/package.scala +++ b/src/main/scala/org/perl8/test/tap/package.scala @@ -1,5 +1,10 @@ package org.perl8.test +/** Classes for TAP generation and parsing. + */ package object tap { + /** Exception representing an error during parsing. It is thrown when a TAP + * line isn't recognized. + */ case class ParseException (message: String) extends RuntimeException(message) } -- cgit v1.2.3-54-g00ecf