From 8478ecf1dff69f28ea0850993faca43729e2cde0 Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Fri, 1 Mar 2013 18:01:14 -0600 Subject: more docs --- src/main/scala/org/perl8/test/tap/TAPEvent.scala | 37 ++++++++++-- src/main/scala/org/perl8/test/tap/TAPResult.scala | 74 ++++++++++++++++++----- 2 files changed, 92 insertions(+), 19 deletions(-) diff --git a/src/main/scala/org/perl8/test/tap/TAPEvent.scala b/src/main/scala/org/perl8/test/tap/TAPEvent.scala index 184e7ab..0f9318b 100644 --- a/src/main/scala/org/perl8/test/tap/TAPEvent.scala +++ b/src/main/scala/org/perl8/test/tap/TAPEvent.scala @@ -2,11 +2,38 @@ package org.perl8.test.tap import org.perl8.test.Plan +/** An event emitted while parsing a TAP stream. */ sealed trait TAPEvent + +/** The start of a TAP stream. */ case object StartEvent extends TAPEvent -case class EndEvent (result: TAPResult) extends TAPEvent -case class ResultEvent (result: TestResult) extends TAPEvent -case class PlanEvent (plan: Plan) extends TAPEvent + +/** The end of a TAP stream. + * @param result The [[org.perl8.test.tap.TAPResult TAPResult]] containing + * information about all of the tests which just finished + * running. This will be the same thing that is returned by the + * call to [[org.perl8.test.tap.Parser Parser]]'s `parse` + * method. + */ +case class EndEvent private[tap] (result: TAPResult) extends TAPEvent + +/** An individual test result. + * @param result The [[org.perl8.test.tap.TestResult TestResult]] containing + * information about the corresponding test. + */ +case class ResultEvent private[tap] (result: TestResult) extends TAPEvent + +/** A test plan. + * @param plan The [[org.perl8.test.Plan Plan]] corresponding to the line that + * was parsed. + */ +case class PlanEvent private[tap] (plan: Plan) extends TAPEvent + +/** The start of a subtest (currently unused). */ case object SubtestStartEvent extends TAPEvent -case class SubtestEndEvent (result: TestResult) extends TAPEvent -case class CommentEvent (text: String) extends TAPEvent + +/** The end of a subtest (currently unused). */ +case class SubtestEndEvent private[tap] (result: TestResult) extends TAPEvent + +/** A comment (currently unused). */ +case class CommentEvent private[tap] (text: String) extends TAPEvent diff --git a/src/main/scala/org/perl8/test/tap/TAPResult.scala b/src/main/scala/org/perl8/test/tap/TAPResult.scala index 21c7986..2a23122 100644 --- a/src/main/scala/org/perl8/test/tap/TAPResult.scala +++ b/src/main/scala/org/perl8/test/tap/TAPResult.scala @@ -2,37 +2,47 @@ package org.perl8.test.tap import org.perl8.test.{Plan,NumericPlan,SkipAll} -sealed trait Directive { - val message: Option[String] -} -case class SkipDirective (message: Option[String]) extends Directive -case class TodoDirective (message: Option[String]) extends Directive - -class TestResult ( - val passed: Boolean, - val number: Int, - val description: String, - val directive: Option[Directive], - val subtest: Option[TAPResult] -) - +/** The summarized results of a TAP stream. Contains the + * [[org.perl8.test.Plan Plan]] that was given, as well as a list of + * [[org.perl8.test.tap.TestResult TestResults]] corresponding to each of the + * tests in the stream. + * + * @param plan The [[org.perl8.test.Plan Plan]] from the TAP stream + * @param results The list of [[org.perl8.test.tap.TestResult TestResults]] + * from the TAP stream + */ class TAPResult (val plan: Plan, val results: Seq[TestResult]) { + /** Returns true if the number of tests executed was compatible with the + * provided test plan. + */ val matchesPlan = plan match { case NumericPlan(n) => results.length == n case _ => results.length == 0 } + /** Returns the number of test failures in the TAP stream. */ val fails = results.count { r => !r.passed && !r.directive.isDefined } + /** Returns true if all of the tests passed. */ val testsPassed = fails == 0 + /** Returns true if the TAP stream overall passed. + * + * Differs from `testsPassed` in that it also takes into account things + * like invalid plans. + */ val success = plan match { case SkipAll(_) => true case _ => results.length > 0 && fails == 0 && matchesPlan } + /** Returns the exit code to use if running this test on its own. + * + * Success is indicated by 0, invalid TAP streams (such as incorrect plans) + * by 255, and other kinds of failures by the failure count. + */ val exitCode = if (success) { 0 @@ -44,3 +54,39 @@ class TAPResult (val plan: Plan, val results: Seq[TestResult]) { fails } } + +/** The result of a single test. + * + * @param passed True if the test passed + * @param number The test number in the TAP stream + * @param description The test description + * @param directive The [[org.perl8.test.tap.Directive Directive]] (either + * skip or todo) that was provided for this test, if any + * @param subtest The [[org.perl8.test.tap.TAPResult]] for the subtest + * that this test corresponds to, if any + */ +class TestResult ( + val passed: Boolean, + val number: Int, + val description: String, + val directive: Option[Directive], + val subtest: Option[TAPResult] +) + +/** A modifier associated with a test result. This is indicated by a `#` at + * the end of the result line, followed by the type of directive, and an + * optional message. + */ +sealed trait Directive { + val message: Option[String] +} + +/** A directive indicating that this test was skipped. */ +case class SkipDirective private[tap] ( + message: Option[String] +) extends Directive + +/** A directive indicating that this test is known to fail. */ +case class TodoDirective private[tap] ( + message: Option[String] +) extends Directive -- cgit v1.2.3