Prettifier

A function that given any object will produce a “pretty” string representation of that object, where “pretty” is in the eye of the implementer.

Scala's Any type declares a toString that will convert any object to a String representation. This String representation is primarily intended for programmers, and is usually sufficient. However, sometimes it can be helpful to provide an alternative implementation of toString for certain types. For example, the toString implementation on String prints out the value of the String:

scala> "1".toString
res0: String = 1

If the error message that resulted from comparing Int 1 with String "1" in a ScalaTest assertion used toString, therefore, the error message would be:

1 did not equal 1

To make it quicker to figure out why the assertion failed, ScalaTest ''prettifies'' the objects involved in the error message. The default Prettifier will place double quotes on either side of a Strings toString result:

scala> import org.scalactic._
import org.scalactic._

scala> Prettifier.default("1")
res1: String = "1"

Thus the error message resulting from comparing Int 1 with String "1", in a ScalaTest assertion is:

1 did not equal "1"

If you wish to prettify an object in production code, for example, to issue a profoundly clear debug message, you can use PrettyMethods and invoke pretty. Here's an example:

scala> import PrettyMethods._
import PrettyMethods._

scala> 1.pretty
res2: String = 1

scala> "1".pretty
res3: String = "1"

For example, the default Prettifier, Prettifier.default, transforms:

• Null to: null

• Unit to: <() the Unit value>

• String to: "string" (the toString result surrounded by double quotes)

• Char to: 'c' (the toString result surrounded by single quotes)

• Array to: Array("1", "2", "3")

• scala.Some to: Some("3")

• scala.util.Left to: Left("3")

• scala.util.Right to: Right("3")

• scala.util.Success to: Success("3")

• org.scalactic.Good to: Good("3")

• org.scalactic.Bad to: Bad("3")

• org.scalactic.One to: One("3")

• org.scalactic.Many to: Many("1", "2", "3")

• scala.collection.Iterable to: List("1", "2", "3")

• java.util.Collection to: ["1", "2", "3"]

• java.util.Map to: {1="one", 2="two", 3="three"}

For anything else, the default Prettifier returns the result of invoking toString.

Note: Prettifier is not parameterized (''i.e.'', Prettifier[T], where T is the type to prettify) because assertions (including matcher expressions) in ScalaTest would then need to look up Prettifiers implicitly by type. This would slow compilation even though most (let's guess 99.9%) of the time in practice assertions do not fail, and thus 99.9% of the time no error messages need to be generated. If no error messages are needed 99.9% of the time, no prettification is needed 99.9% of the time, so the slow down in compile time for the implicit look ups is unlikely to be worth the benefit. Only a few types in practice usually need prettification for testing error message purposes, and those will be covered by the default Prettifier. A future version of ScalaTest will provide a simple mechanism to replace the default Prettifier with a custom one when a test actually fails.