garrity-software/gs-test
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Pre-commit.

Browse source
This commit is contained in:
Pat Garrity 2024-09-03 22:05:51 -05:00
parent 789fc594a2
commit 79e6672bdf
Signed by: pfm
GPG key ID: 5CA5D21BAB7F3A76
15 changed files with 519 additions and 440 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
build.sbt
View file

@ -62,20 +62,28 @@ lazy val `api-definition` = project
.in(file("modules/api-definition"))
.settings(sharedSettings)
.settings(testSettings)
.settings(name := s"${gsProjectName.value}-api-definition-v${semVerMajor.value}")
.settings(libraryDependencies ++= Seq(
.settings(
name := s"${gsProjectName.value}-api-definition-v${semVerMajor.value}"
)
.settings(
libraryDependencies ++= Seq(
Deps.Cats.Core,
Deps.Cats.Effect,
Deps.Fs2.Core
))
)
)
lazy val `api-execution` = project
.in(file("modules/api-execution"))
.settings(sharedSettings)
.settings(testSettings)
.settings(name := s"${gsProjectName.value}-api-execution-v${semVerMajor.value}")
.settings(libraryDependencies ++= Seq(
.settings(
name := s"${gsProjectName.value}-api-execution-v${semVerMajor.value}"
)
.settings(
libraryDependencies ++= Seq(
Deps.Cats.Core,
Deps.Cats.Effect,
Deps.Fs2.Core
))
)
)

28
modules/api-definition/src/main/scala/gs/test/v0/definition/Assertion.scala
View file

@ -13,32 +13,40 @@ object Assertion:
// TODO: Code Position
case object IsEqualTo extends Assertion("isEqualTo"):
def evaluate[A: ClassTag](
candidate: A,
expected: A
)(using CanEqual[A, A]): Either[TestFailure, Unit] =
if candidate == expected then
success()
)(
using
CanEqual[A, A]
): Either[TestFailure, Unit] =
if candidate == expected then success()
else
val runtimeType = classTag[A].runtimeClass.getName()
Left(TestFailure.AssertionFailed(
Left(
TestFailure.AssertionFailed(
assertionName = name,
inputs = Map(
"candidate" -> runtimeType,
"expected" -> runtimeType
),
message = s"'${renderInput(candidate)}' was not equal to '${renderInput(candidate)}'"
))
message =
s"'${renderInput(candidate)}' was not equal to '${renderInput(candidate)}'"
)
)
case object IsTrue extends Assertion("isTrue"):
def evaluate(candidate: Boolean): Either[TestFailure, Unit] =
if candidate then
success()
if candidate then success()
else
Left(TestFailure.AssertionFailed(
Left(
TestFailure.AssertionFailed(
assertionName = name,
inputs = Map("candidate" -> "Boolean"),
message = s"Expected '$candidate' to be 'true'."
))
)
)
end Assertion

19
modules/api-definition/src/main/scala/gs/test/v0/definition/Check.scala
View file

@ -1,7 +1,7 @@
package gs.test.v0.definition
import scala.reflect.ClassTag
import cats.effect.Sync
import scala.reflect.ClassTag
opaque type Check[A] = A
@ -12,20 +12,29 @@ object Check:
def apply[A](candidate: A): Check[A] = candidate
extension [A: ClassTag](check: Check[A])
/**
* @return The unwrapped value of this [[Check]].
/** @return
* The unwrapped value of this [[Check]].
*/
def unwrap(): A = check
def isEqualTo(expected: A)(using CanEqual[A, A]): TestResult =
def isEqualTo(
expected: A
)(
using
CanEqual[A, A]
): TestResult =
Assertion.IsEqualTo.evaluate(check, expected)
def isEqualToF[F[_]: Sync](
expected: A
)(using CanEqual[A, A]): F[TestResult] =
)(
using
CanEqual[A, A]
): F[TestResult] =
Sync[F].delay(isEqualTo(expected))
extension (check: Check[Boolean])
def isTrue(): TestResult =
Assertion.IsTrue.evaluate(check)

9
modules/api-definition/src/main/scala/gs/test/v0/definition/Marker.scala
View file

@ -1,12 +1,12 @@
package gs.test.v0.definition
/**
* Enumeration for _Markers_, special tokens which "mark" a test to change
/** Enumeration for _Markers_, special tokens which "mark" a test to change
* execution functionality.
*
* The basic case for this enumeration is allowing tests to be ignored.
*
* @param name The formal serialized name of the marker.
* @param name
* The formal serialized name of the marker.
*/
sealed abstract class Marker(val name: String)
@ -14,8 +14,7 @@ object Marker:
given CanEqual[Marker, Marker] = CanEqual.derived
/**
* If this [[Marker]] is present on a test, the test will be ignored.
/** If this [[Marker]] is present on a test, the test will be ignored.
*/
case object Ignored extends Marker("ignored")

22
modules/api-definition/src/main/scala/gs/test/v0/definition/PermanentId.scala
View file

@ -2,8 +2,7 @@ package gs.test.v0.definition
import cats.Show
/**
* Opaque type representing some _permanent identifier_. These are
/** Opaque type representing some _permanent identifier_. These are
* user-assigned strings that are expected to _not change over time_ for some
* test. This allows tests to be deterministically tracked. The only constraint
* for a permanent identifier is that it must not be blank.
@ -18,18 +17,21 @@ opaque type PermanentId = String
object PermanentId:
/**
* Instantiate a new [[PermanentId]].
/** Instantiate a new [[PermanentId]].
*
* @param candidate The candidate string.
* @return The new [[PermanentId]] instance.
* @throws IllegalArgumentException If the candidate string is blank.
* @param candidate
* The candidate string.
* @return
* The new [[PermanentId]] instance.
* @throws IllegalArgumentException
* If the candidate string is blank.
*/
def apply(candidate: String): PermanentId =
if candidate.isBlank() then
throw new IllegalArgumentException("Permanent Identifiers must be non-blank.")
else
candidate
throw new IllegalArgumentException(
"Permanent Identifiers must be non-blank."
)
else candidate
given CanEqual[PermanentId, PermanentId] = CanEqual.derived

12
modules/api-definition/src/main/scala/gs/test/v0/definition/Tag.scala
View file

@ -2,18 +2,18 @@ package gs.test.v0.definition
import cats.Show
/**
* Opaque type representing tags that may be assigned to a [[Test]].
/** Opaque type representing tags that may be assigned to a [[Test]].
*/
opaque type Tag = String
object Tag:
/**
* Instantiate a new [[Tag]].
/** Instantiate a new [[Tag]].
*
* @param tag The candidate string.
* @return The new [[Tag]] instance.
* @param tag
* The candidate string.
* @return
* The new [[Tag]] instance.
*/
def apply(tag: String): Tag = tag

38
modules/api-definition/src/main/scala/gs/test/v0/definition/TestDefinition.scala
View file

@ -1,18 +1,24 @@
package gs.test.v0.definition
import cats.data.EitherT
import cats.Show
import cats.data.EitherT
/**
* Each instance of this class indicates the _definition_ of some test.
/** Each instance of this class indicates the _definition_ of some test.
*
* @param name The display name of the test. Not considered to be unique.
* @param permanentId The [[PermanentId]] for this test.
* @param documentation The documentation for this test.
* @param tags The list of [[Tag]] applicable to this test.
* @param markers The list of [[Marker]] applicable to this test.
* @param iterations The number of iterations of this test to run.
* @param unitOfWork The function that the test evaluates.
* @param name
* The display name of the test. Not considered to be unique.
* @param permanentId
* The [[PermanentId]] for this test.
* @param documentation
* The documentation for this test.
* @param tags
* The list of [[Tag]] applicable to this test.
* @param markers
* The list of [[Marker]] applicable to this test.
* @param iterations
* The number of iterations of this test to run.
* @param unitOfWork
* The function that the test evaluates.
*/
final class TestDefinition[F[_]](
val name: TestDefinition.Name,
@ -26,19 +32,19 @@ final class TestDefinition[F[_]](
object TestDefinition:
/**
* Opaque type representing names that may be assigned to [[Test]].
/** Opaque type representing names that may be assigned to [[Test]].
*/
opaque type Name = String
object Name:
/**
* Instantiate a new [[Test.Name]]. This name is not unique, has no
/** Instantiate a new [[Test.Name]]. This name is not unique, has no
* constraints, and only exists for display purposes.
*
* @param name The candidate string.
* @return The new [[Test.Name]] instance.
* @param name
* The candidate string.
* @return
* The new [[Test.Name]] instance.
*/
def apply(name: String): Name = name

29
modules/api-definition/src/main/scala/gs/test/v0/definition/TestFailure.scala
View file

@ -1,19 +1,20 @@
package gs.test.v0.definition
/**
* Base trait for all failures recognized by gs-test.
/** Base trait for all failures recognized by gs-test.
*/
sealed trait TestFailure
object TestFailure:
/**
* Returned when assertions in this library fail. Assertions understand how to
* populate these values.
/** Returned when assertions in this library fail. Assertions understand how
* to populate these values.
*
* @param assertionName The name of the assertion.
* @param inputs The names and calculated types of each input to the assertion.
* @param message The message produced by the assertion.
* @param assertionName
* The name of the assertion.
* @param inputs
* The names and calculated types of each input to the assertion.
* @param message
* The message produced by the assertion.
*/
case class AssertionFailed(
assertionName: String,
@ -21,19 +22,19 @@ object TestFailure:
message: String
) extends TestFailure
/**
* Return when a test explicitly calls `fail("...")` or some variant thereof.
/** Return when a test explicitly calls `fail("...")` or some variant thereof.
*
* @param message The failure message provided by the test author.
* @param message
* The failure message provided by the test author.
*/
case class TestRequestedFailure(
message: String
) extends TestFailure
/**
* Used when the test fails due to an exception.
/** Used when the test fails due to an exception.
*
* @param cause The underlying cause of failure.
* @param cause
* The underlying cause of failure.
*/
case class ExceptionThrown(
cause: Throwable

286
modules/api-definition/src/main/scala/gs/test/v0/definition/TestGroup.scala
View file

@ -1,14 +1,13 @@
package gs.test.v0.definition
import cats.syntax.all.*
import cats.effect.Async
import scala.collection.mutable.ListBuffer
import cats.data.EitherT
import cats.effect.Async
import cats.syntax.all.*
import java.util.concurrent.ConcurrentHashMap
import scala.collection.mutable.ListBuffer
import scala.jdk.CollectionConverters.*
/**
* Base class for defining groups of related tests. Users should extend this
/** Base class for defining groups of related tests. Users should extend this
* class to define their tests.
*
* ## Example
@ -27,23 +26,23 @@ import scala.jdk.CollectionConverters.*
* }}}
*/
abstract class TestGroup[F[_]: Async]:
/**
* @return The display name for this group.
/** @return
* The display name for this group.
*/
def name: String
/**
* @return List of [[Tag]] that apply to all tests within this group.
/** @return
* List of [[Tag]] that apply to all tests within this group.
*/
def tags: List[Tag] = List.empty
/**
* @return List of all [[Marker]] that apply to all tests within this group.
/** @return
* List of all [[Marker]] that apply to all tests within this group.
*/
def markers: List[Marker] = List.empty
/**
* @return The documentation for this group.
/** @return
* The documentation for this group.
*/
def documentation: Option[String] = None
@ -54,10 +53,10 @@ abstract class TestGroup[F[_]: Async]:
private val registry: TestGroup.Registry[F] = new TestGroup.Registry[F]
/**
* Compile the contents of this [[TestGroup]] for delivery to the engine.
/** Compile the contents of this [[TestGroup]] for delivery to the engine.
*
* @return The immutable, compiled form of this [[TestGroup]].
* @return
* The immutable, compiled form of this [[TestGroup]].
*/
def compile(): TestGroupDefinition[F] =
new TestGroupDefinition[F](
@ -72,46 +71,45 @@ abstract class TestGroup[F[_]: Async]:
tests = registry.toList()
)
/**
* Provide an effect that must run before any of the tests within this group
/** Provide an effect that must run before any of the tests within this group
* are executed.
*
* @param f The effect to run.
* @param f
* The effect to run.
*/
protected def beforeGroup(f: => F[Unit]): Unit =
beforeGroupValue = Some(f)
()
/**
* Provide an effect that must run after all tests within this group have
/** Provide an effect that must run after all tests within this group have
* finished execution.
*
* @param f The effect to run.
* @param f
* The effect to run.
*/
protected def afterGroup(f: => F[Unit]): Unit =
afterGroupValue = Some(f)
()
/**
* Provide an effect that must run before each test within this group.
/** Provide an effect that must run before each test within this group.
*
* @param f The effect to run.
* @param f
* The effect to run.
*/
protected def beforeEachTest(f: => F[Unit]): Unit =
beforeEachTestValue = Some(f)
()
/**
* Provide an effect that must run after each test within this group.
/** Provide an effect that must run after each test within this group.
*
* @param f The effect to run.
* @param f
* The effect to run.
*/
protected def afterEachTest(f: => F[Unit]): Unit =
afterEachTestValue = Some(f)
()
/**
* Define a new test.
/** Define a new test.
*
* ## Required Information
*
@ -129,9 +127,12 @@ abstract class TestGroup[F[_]: Async]:
* parent group. If this group contains tag "foo", any test within this group
* will also get tag "foo".
*
* @param permanentId The [[PermanentId]] for this test.
* @param name The display name for this test.
* @return A builder, to help complete test definition.
* @param permanentId
* The [[PermanentId]] for this test.
* @param name
* The display name for this test.
* @return
* A builder, to help complete test definition.
*/
protected def test(
permanentId: PermanentId,
@ -142,92 +143,105 @@ abstract class TestGroup[F[_]: Async]:
name = TestDefinition.Name(name),
permanentId = permanentId,
tags = ListBuffer(tags*),
markers = ListBuffer(markers*),
markers = ListBuffer(markers*)
)
object TestGroup:
/**
* Specialization of [[TestGroup]] for `cats.effect.IO`, the typical use case.
/** Specialization of [[TestGroup]] for `cats.effect.IO`, the typical use
* case.
*/
abstract class IO extends TestGroup[cats.effect.IO]
/**
* Builder to assist with defining tests.
/** Builder to assist with defining tests.
*
* @param registry Registry instance internal to a [[TestGroup]] for recording completed definitions.
* @param name The name of the test.
* @param permanentId The [[PermanentId]] of the test.
* @param tags List of [[TestDefinition.Tag]] applicable to this test.
* @param markers List of [[TestDefinition.Marker]] applicable to this test.
* @param documentation The documentation for this test.
* @param iterations Number of iterations to run this test.
* @param registry
* Registry instance internal to a [[TestGroup]] for recording completed
* definitions.
* @param name
* The name of the test.
* @param permanentId
* The [[PermanentId]] of the test.
* @param tags
* List of [[TestDefinition.Tag]] applicable to this test.
* @param markers
* List of [[TestDefinition.Marker]] applicable to this test.
* @param documentation
* The documentation for this test.
* @param iterations
* Number of iterations to run this test.
*/
protected final class TestBuilder[F[_]: Async](
final protected class TestBuilder[F[_]: Async](
val registry: Registry[F],
val name: TestDefinition.Name,
val permanentId: PermanentId,
private val tags: ListBuffer[Tag],
private val markers: ListBuffer[Marker],
private var documentation: Option[String] = None,
private var iterations: TestIterations = TestIterations.One,
private var iterations: TestIterations = TestIterations.One
):
/**
* Supply documentation for this test.
/** Supply documentation for this test.
*
* @param docs The documentation for this test.
* @return This builder.
* @param docs
* The documentation for this test.
* @return
* This builder.
*/
def document(docs: String): TestBuilder[F] =
documentation = Some(docs)
this
/**
* Add additional [[Test.Tag]] to this test definition.
/** Add additional [[Test.Tag]] to this test definition.
*
* @param additionalTags The list of new tags.
* @return This builder.
* @param additionalTags
* The list of new tags.
* @return
* This builder.
*/
def tagged(additionalTags: Tag*): TestBuilder[F] =
val _ = tags.addAll(additionalTags)
this
/**
* Add the [[TestDefinition.Marker.Ignored]] marker to this test definition.
/** Add the [[TestDefinition.Marker.Ignored]] marker to this test
* definition.
*
* @return This builder.
* @return
* This builder.
*/
def ignored(): TestBuilder[F] =
val _ = markers.addOne(Marker.Ignored)
this
/**
* Add one or more [[TestDefinition.Marker]] to this test definition.
/** Add one or more [[TestDefinition.Marker]] to this test definition.
*
* @param additionalMarkers The list of markers to add.
* @return This builder.
* @param additionalMarkers
* The list of markers to add.
* @return
* This builder.
*/
def marked(additionalMarkers: Marker*): TestBuilder[F] =
val _ = markers.addAll(additionalMarkers)
this
/**
* Set the number of times this test should iterate.
/** Set the number of times this test should iterate.
*
* @param iters The number of iterations.
* @return This builder.
* @param iters
* The number of iterations.
* @return
* This builder.
*/
def iterate(iters: TestIterations): TestBuilder[F] =
iterations = iters
this
/**
* Provide an input supplier for this test. Note that each iteration of the
/** Provide an input supplier for this test. Note that each iteration of the
* test results in the input function being evaluated.
*
* @param f The input function.
* @return Builder that supports input.
* @param f
* The input function.
* @return
* Builder that supports input.
*/
def input[Input](f: F[Input]): InputTestBuilder[F, Input] =
new InputTestBuilder[F, Input](
@ -240,29 +254,30 @@ object TestGroup:
iterations = iterations
)
/**
* Finalize and register this test with a pure unit of work.
/** Finalize and register this test with a pure unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def pure(unitOfWork: => Either[TestFailure, Unit]): Unit =
apply(EitherT.fromEither[F](unitOfWork))
/**
* Finalize and register this test with an effectful unit of work.
/** Finalize and register this test with an effectful unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def effectful(unitOfWork: => F[Either[TestFailure, Unit]]): Unit =
apply(EitherT(unitOfWork))
/**
* Finalize and register this test with an effectful unit of work.
/** Finalize and register this test with an effectful unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def apply(unitOfWork: => EitherT[F, TestFailure, Unit]): Unit =
registry.register(new TestDefinition[F](
registry.register(
new TestDefinition[F](
name = name,
permanentId = permanentId,
documentation = documentation,
@ -270,22 +285,31 @@ object TestGroup:
markers = markers.distinct.toList,
iterations = iterations,
unitOfWork = unitOfWork
))
)
)
/**
* Builder to assist with defining tests. This builder is for tests which
/** Builder to assist with defining tests. This builder is for tests which
* accept input via some producing function.
*
* @param registry Registry instance internal to a [[TestGroup]] for recording completed definitions.
* @param name The name of the test.
* @param permanentId The [[PermanentId]] of the test.
* @param inputFunction The function that provides input to this test.
* @param tags List of [[TestDefinition.Tag]] applicable to this test.
* @param markers List of [[TestDefinition.Marker]] applicable to this test.
* @param documentation The documentation for this test.
* @param iterations Number of iterations to run this test.
* @param registry
* Registry instance internal to a [[TestGroup]] for recording completed
* definitions.
* @param name
* The name of the test.
* @param permanentId
* The [[PermanentId]] of the test.
* @param inputFunction
* The function that provides input to this test.
* @param tags
* List of [[TestDefinition.Tag]] applicable to this test.
* @param markers
* List of [[TestDefinition.Marker]] applicable to this test.
* @param documentation
* The documentation for this test.
* @param iterations
* Number of iterations to run this test.
*/
protected final class InputTestBuilder[F[_]: Async, Input](
final protected class InputTestBuilder[F[_]: Async, Input](
val registry: Registry[F],
val name: TestDefinition.Name,
val permanentId: PermanentId,
@ -293,80 +317,87 @@ object TestGroup:
private val tags: ListBuffer[Tag],
private val markers: ListBuffer[Marker],
private var documentation: Option[String] = None,
private var iterations: TestIterations = TestIterations.One,
private var iterations: TestIterations = TestIterations.One
):
/**
* Supply documentation for this test.
/** Supply documentation for this test.
*
* @param docs The documentation for this test.
* @return This builder.
* @param docs
* The documentation for this test.
* @return
* This builder.
*/
def document(docs: String): InputTestBuilder[F, Input] =
documentation = Some(docs)
this
/**
* Add additional [[Test.Tag]] to this test definition.
/** Add additional [[Test.Tag]] to this test definition.
*
* @param additionalTags The list of new tags.
* @return This builder.
* @param additionalTags
* The list of new tags.
* @return
* This builder.
*/
def tagged(additionalTags: Tag*): InputTestBuilder[F, Input] =
val _ = tags.addAll(additionalTags)
this
/**
* Add the [[TestDefinition.Marker.Ignored]] marker to this test definition.
/** Add the [[TestDefinition.Marker.Ignored]] marker to this test
* definition.
*
* @return This builder.
* @return
* This builder.
*/
def ignored(): InputTestBuilder[F, Input] =
val _ = markers.addOne(Marker.Ignored)
this
/**
* Add one or more [[TestDefinition.Marker]] to this test definition.
/** Add one or more [[TestDefinition.Marker]] to this test definition.
*
* @param additionalMarkers The list of markers to add.
* @return This builder.
* @param additionalMarkers
* The list of markers to add.
* @return
* This builder.
*/
def marked(additionalMarkers: Marker*): InputTestBuilder[F, Input] =
val _ = markers.addAll(additionalMarkers)
this
/**
* Set the number of times this test should iterate.
/** Set the number of times this test should iterate.
*
* @param iters The number of iterations.
* @return This builder.
* @param iters
* The number of iterations.
* @return
* This builder.
*/
def iterate(iters: TestIterations): InputTestBuilder[F, Input] =
iterations = iters
this
/**
* Finalize and register this test with a pure unit of work.
/** Finalize and register this test with a pure unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def pure(unitOfWork: Input => Either[TestFailure, Unit]): Unit =
apply(input => EitherT(Async[F].delay(unitOfWork(input))))
/**
* Finalize and register this test with an effectful unit of work.
/** Finalize and register this test with an effectful unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def effectful(unitOfWork: Input => F[Either[TestFailure, Unit]]): Unit =
apply(input => EitherT(unitOfWork(input)))
/**
* Finalize and register this test with an effectful unit of work.
/** Finalize and register this test with an effectful unit of work.
*
* @param unitOfWork The function this test will execute.
* @param unitOfWork
* The function this test will execute.
*/
def apply(unitOfWork: Input => EitherT[F, TestFailure, Unit]): Unit =
registry.register(new TestDefinition[F](
registry.register(
new TestDefinition[F](
name = name,
permanentId = permanentId,
documentation = documentation,
@ -374,9 +405,11 @@ object TestGroup:
markers = markers.distinct.toList,
iterations = iterations,
unitOfWork = EitherT.right(inputFunction).flatMap(unitOfWork)
))
)
)
final protected class Registry[F[_]]:
protected final class Registry[F[_]]:
val mapping: ConcurrentHashMap[PermanentId, TestDefinition[F]] =
new ConcurrentHashMap[PermanentId, TestDefinition[F]]
@ -385,8 +418,7 @@ object TestGroup:
throw new IllegalArgumentException(
s"Attempted to register test with duplicate Permanent ID '${test.permanentId.show}'."
)
else
mapping.put(test.permanentId, test)
else mapping.put(test.permanentId, test)
def toList(): List[TestDefinition[F]] = mapping.values().asScala.toList

30
modules/api-definition/src/main/scala/gs/test/v0/definition/TestGroupDefinition.scala
View file

@ -2,16 +2,20 @@ package gs.test.v0.definition
import cats.Show
/**
* Each group is comprised of a list of [[Test]]. This list may be empty.
/** Each group is comprised of a list of [[Test]]. This list may be empty.
*
* Groups are essentially metadata for tests for viewing/organization purposes.
*
* @param name The group name. Not considered to be unique.
* @param documentation Arbitrary documentation for this group of tests.
* @param testTags Set of tags applied to all [[TestDefinition]] within the group.
* @param testMarkers Set of markers applied to all [[TestDefinition]] within the group.
* @param tests The list of tests in this group.
* @param name
* The group name. Not considered to be unique.
* @param documentation
* Arbitrary documentation for this group of tests.
* @param testTags
* Set of tags applied to all [[TestDefinition]] within the group.
* @param testMarkers
* Set of markers applied to all [[TestDefinition]] within the group.
* @param tests
* The list of tests in this group.
*/
final class TestGroupDefinition[F[_]](
val name: TestGroupDefinition.Name,
@ -27,19 +31,19 @@ final class TestGroupDefinition[F[_]](
object TestGroupDefinition:
/**
* Opaque type representing names that may be assigned to test groups.
/** Opaque type representing names that may be assigned to test groups.
*/
opaque type Name = String
object Name:
/**
* Instantiate a new [[TestGroup.Name]]. This name is not unique, has no
/** Instantiate a new [[TestGroup.Name]]. This name is not unique, has no
* constraints, and only exists for display purposes.
*
* @param name The candidate string.
* @return The new [[TestGroup.Name]] instance.
* @param name
* The candidate string.
* @return
* The new [[TestGroup.Name]] instance.
*/
def apply(name: String): Name = name

20
modules/api-definition/src/main/scala/gs/test/v0/definition/TestIterations.scala
View file

@ -2,9 +2,8 @@ package gs.test.v0.definition
import cats.Show
/**
* Opaque type that represents the number of iterations a test should run.
* This value must be at least `1` (the default). To ignore a test, use the
/** Opaque type that represents the number of iterations a test should run. This
* value must be at least `1` (the default). To ignore a test, use the
* [[Test.Marker.Ignored]] marker.
*/
opaque type TestIterations = Int
@ -13,25 +12,24 @@ object TestIterations:
def One: TestIterations = 1
/**
* Validate and instantiate a new [[TestIterations]] instance.
/** Validate and instantiate a new [[TestIterations]] instance.
*
* @param candidate The candidate value. Must be 1 or greater.
* @return The new [[TestIterations]], or an error if an invalid input is given.
* @param candidate
* The candidate value. Must be 1 or greater.
* @return
* The new [[TestIterations]], or an error if an invalid input is given.
*/
def apply(candidate: Int): TestIterations =
if candidate < 1 then
throw new IllegalArgumentException(
s"Tests must iterate at least once. Received candidate '$candidate'."
)
else
candidate
else candidate
given CanEqual[TestIterations, TestIterations] = CanEqual.derived
given Show[TestIterations] = iters => iters.toString()
extension (iters: TestIterations)
def toInt(): Int = iters
extension (iters: TestIterations) def toInt(): Int = iters
end TestIterations

12
modules/api-definition/src/main/scala/gs/test/v0/definition/TestSuite.scala
View file

@ -1,16 +1,18 @@
package gs.test.v0.definition
/**
* The Test Suite is the primary unit of organization within `gs-test` -- each
/** The Test Suite is the primary unit of organization within `gs-test` -- each
* execution _typically_ runs a single test suite. For example, the unit tests
* for some project would likely comprise of a single suite.
*
* Within each suite is a list of [[TestGroup]], arbitrary ways to organize
* individual [[Test]] definitions.
*
* @param name The name of this test suite.
* @param documentation Arbitrary documentation for this suite of tests.
* @param groups List of [[TestGroup]] owned by this suite.
* @param name
* The name of this test suite.
* @param documentation
* Arbitrary documentation for this suite of tests.
* @param groups
* List of [[TestGroup]] owned by this suite.
*/
case class TestSuite[F[_]](
name: String,

75
modules/api-definition/src/main/scala/gs/test/v0/definition/syntax.scala
View file

@ -5,8 +5,7 @@ import cats.data.EitherT
import cats.effect.Sync
import cats.syntax.all.*
/**
* String interpolator for [[Tag]]. Shorthand for producing new [[Tag]]
/** String interpolator for [[Tag]]. Shorthand for producing new [[Tag]]
* instances.
*
* {{{
@ -14,11 +13,9 @@ import cats.syntax.all.*
* val tag1: TestDefinition.Tag = tag"example"
* }}}
*/
extension (sc: StringContext)
def tag(args: Any*): Tag = Tag(sc.s(args*))
extension (sc: StringContext) def tag(args: Any*): Tag = Tag(sc.s(args*))
/**
* String interpolator for [[PermanentId]]. Shorthand for producing new
/** String interpolator for [[PermanentId]]. Shorthand for producing new
* [[PermanentId]] instances.
*
* {{{
@ -29,35 +26,37 @@ extension (sc: StringContext)
extension (sc: StringContext)
def pid(args: Any*): PermanentId = PermanentId(sc.s(args*))
/**
* Request this test to fail (pure form).
/** Request this test to fail (pure form).
*
* @param message The message to report - why did this test fail?
* @return The failing test result.
* @param message
* The message to report - why did this test fail?
* @return
* The failing test result.
*/
def fail(message: String): Either[TestFailure, Unit] =
Left(TestFailure.TestRequestedFailure(message))
/**
* Request this test to fail (lifted into F).
/** Request this test to fail (lifted into F).
*
* @param message The message to report - why did this test fail?
* @return The failing test result.
* @param message
* The message to report - why did this test fail?
* @return
* The failing test result.
*/
def failF[F[_]: Applicative](message: String): F[Either[TestFailure, Unit]] =
Applicative[F].pure(fail(message))
/**
* Request this test to fail (lifted into EitherT).
/** Request this test to fail (lifted into EitherT).
*
* @param message The message to report - why did this test fail?
* @return The failing test result.
* @param message
* The message to report - why did this test fail?
* @return
* The failing test result.
*/
def failT[F[_]: Applicative](message: String): EitherT[F, TestFailure, Unit] =
EitherT(failF(message))
/**
* Shorthand for indicating a passing test (pure form).
/** Shorthand for indicating a passing test (pure form).
*
* ## Example
*
@ -70,12 +69,12 @@ def failT[F[_]: Applicative](message: String): EitherT[F, TestFailure, Unit] =
* test(pid"ex", "Example Test").pure { pass() }
* }}}
*
* @return The passing test result.
* @return
* The passing test result.
*/
def pass(): Either[TestFailure, Unit] = Right(())
/**
* Shorthand for indicating a passing test (lifted into F).
/** Shorthand for indicating a passing test (lifted into F).
*
* ## Example
*
@ -88,13 +87,13 @@ def pass(): Either[TestFailure, Unit] = Right(())
* test(pid"ex", "Example Test").effectful { passF() }
* }}}
*
* @return The passing test result.
* @return
* The passing test result.
*/
def passF[F[_]: Applicative](): F[Either[TestFailure, Unit]] =
Applicative[F].pure(Right(()))
/**
* Shorthand for indicating a passing test (lifted into EitherT).
/** Shorthand for indicating a passing test (lifted into EitherT).
*
* ## Example
*
@ -107,23 +106,29 @@ def passF[F[_]: Applicative](): F[Either[TestFailure, Unit]] =
* test(pid"ex", "Example Test") { passT() }
* }}}
*
* @return The passing test result.
* @return
* The passing test result.
*/
def passT[F[_]: Applicative](): EitherT[F, TestFailure, Unit] =
EitherT(passF())
/**
* Check all of the given results, returning the first failure, or a successful
/** Check all of the given results, returning the first failure, or a successful
* result if no result failed.
*
* @param results The list of results to check.
* @return Successful result or the first failure.
* @param results
* The list of results to check.
* @return
* Successful result or the first failure.
*/
def checkAll(
results: Either[TestFailure, Unit]*
): Either[TestFailure, Unit] =
val initial: Either[TestFailure, Unit] = Right(())
results.foldLeft(initial) { (acc, result) =>
results.foldLeft(initial) {
(
acc,
result
) =>
acc match
case Left(_) => acc
case Right(_) => result
@ -133,7 +138,11 @@ def checkAllF[F[_]: Sync](
checks: F[Either[TestFailure, Unit]]*
): F[Either[TestFailure, Unit]] =
val initial: F[Either[TestFailure, Unit]] = Sync[F].delay(Right(()))
checks.foldLeft(initial) { (acc, result) =>
checks.foldLeft(initial) {
(
acc,
result
) =>
acc.flatMap {
case Right(_) => result
case err => Sync[F].pure(err)

19
modules/api-definition/src/test/scala/gs/test/v0/GroupImplementationTests.scala
View file

@ -1,9 +1,8 @@
package gs.test.v0.definition
import munit.*
import cats.effect.IO
import gs.test.v0.definition.{Tag => GsTag}
import munit.*
class GroupImplementationTests extends FunSuite:
import GroupImplementationTests.*
@ -92,10 +91,11 @@ object GroupImplementationTests:
class G1 extends TestGroup.IO:
override def name: String = "G1"
test(Ids.T1, "simple").pure { Right(()) }
test(Ids.T1, "simple").pure(Right(()))
end G1
class G2 extends TestGroup.IO:
override def name: String =
"G2"
@ -108,12 +108,12 @@ object GroupImplementationTests:
override def markers: List[Marker] =
List(Marker.Ignored)
beforeGroup { IO.unit }
afterGroup { IO.unit }
beforeEachTest { IO.unit }
afterEachTest { IO.unit }
beforeGroup(IO.unit)
afterGroup(IO.unit)
beforeEachTest(IO.unit)
afterEachTest(IO.unit)
test(Ids.T2, "inherit from group").pure { Right(()) }
test(Ids.T2, "inherit from group").pure(Right(()))
end G2
class G3 extends TestGroup.IO:
@ -124,7 +124,8 @@ object GroupImplementationTests:
.tagged(tag"tag1", tag"tag2")
.marked(Marker.Ignored)
.iterate(TestIterations(2))
.pure { Right(()) }
.pure(Right(()))
end G3
end GroupImplementationTests