Capturing Test Results
In the previous tutorial, we reviewed the main Touca functions for describing the behavior and performance of our code under test, by capturing values of important variables and runtime of interesting functions. In this section, we dive a little deeper to explain how Touca tracks values of variables and performance benchmarks.
Preserving Data Types
Touca data capturing functions such as check
, preserve the types of all
captured data so that the Touca server can compare them in their original type.
- Python
- C++
- JavaScript
- Java
touca.check("username", student.username)
touca.check("fullname", student.fullname)
touca.check("birth_date", student.dob)
touca.check("gpa", student.gpa)
In the example above, touca.check
stores value of properties username
and
fullname
as string while properties dob
and gpa
are stored as
datetime.date
and float
respectively. The server visualizes possible
differences in these values based on their types.
The SDK is designed to handle iterables and custom objects by serializing their
elements and properties. This makes it possible for us to add object student
as a single entity, if we so choose.
touca::check("username", student.username);
touca::check("fullname", student.fullname);
touca::check("gpa", student.gpa);
In the example above, touca::check
stores value of properties username
and
fullname
as std::string
while property gpa
is stored as float
. The
server visualizes possible differences in these values based on their types.
touca.check("username", student.username);
touca.check("fullname", student.fullname);
touca.check("birth_date", student.dob);
touca.check("gpa", student.gpa);
In the example above, touca.check
stores value of properties username
and
fullname
as string while properties dob
and gpa
are stored as Date
and
number
respectively. The server visualizes possible differences in these
values based on their types.
The SDK is designed to handle iterables and custom objects by serializing their
elements and properties. This makes it possible for us to add object student
as a single entity, if we so choose.
Touca.check("username", student.username);
Touca.check("fullname", student.fullname);
Touca.check("birth_date", student.dob);
Touca.check("gpa", student.gpa);
In the example above, Touca.check
stores value of properties username
and
fullname
as String
while properties dob
and gpa
are stored as
java.time.LocalDate
and double
respectively. The server visualizes possible
differences in these values based on their types.
The SDK is designed to handle iterables and custom objects by serializing their
elements and properties. This makes it possible for us to add object student
as a single entity, if we so choose.
Customizing Data Serialization
- Python
- C++
- JavaScript
- Java
While Touca data capturing functions automatically support objects and custom types, it is possible to override the serialization logic for any given non-primitive data type.
Consider the following definition for a custom class Course
.
@dataclass
class Course:
name: str
grade: float
By default, the SDK serializes objects of this class using by serializing all of
its public properties. This behavior results in object Course("math", 3.9)
to
be serialized as {name: "math", grade: 3.9}
. We can use touca.add_serializer
to override this default behavior. The following code results in the same object
to be serialized as ["math", 3.9]
:
touca.add_serializer(Course, lambda x: [x.name, x.grade])
for course in student.courses:
touca.add_array_element("courses", course)
touca.add_hit_count("number of courses")
While our serializer changed the way Course
data is serialized and visualized,
it still preserved both properties of this object. If we like to exclude the
property name
during serialization and limit the comparison to grade
, we
could use (x: Course) => x.grade
instead
Touca C++ SDK has built-in support for many commonly-used types of the standard library and can be extended to support custom data types.
Consider the following definition for a user-defined type Date
.
struct Date {
unsigned short year;
unsigned short month;
unsigned short day;
};
Using the natively supported types, we can add a value of type Date
as three
separate test results that each cover individual member variables. But this
practice is cumbersome and impractical for real-world complex data types. To
solve this, we can extend Touca type system to support type Date
using partial
template specialization.
#include "touca/touca.hpp"
template <>
struct touca::serializer<Date> {
data_point serialize(const Date& value) {
return object("Date")
.add("year", value.year)
.add("month", value.month)
.add("day", value.day);
}
};
Once the client library learns how to handle a custom type, it automatically
supports handling it as sub-component of other types. As an example, with the
above-mentioned partial template specialization for type Date
, we can start
adding test results of type std::vector<Date>
or std::map<string, Date>
.
Additionally, supporting type Date
enables objects of this type to be used as
smaller components of even more complex types.
touca::check("birth_date", student.dob);
Consult with the Reference API documentation for more information and examples for supporting custom types.
Touca SDKs have native support for primitive data types such as integers and floating point numbers, characters and string, arrays and maps, and other commonly used data types. You can extend and override the built-in serialization logic for any given non-primitive data type.
Consider the following definition for a custom class Course
.
export class Course {
constructor(public readonly name: string, public readonly grade: number) {}
}
By default, the SDK serializes objects of this class using by serializing all of
its public properties. This behavior results in object Course('math', 3.9)
to
be serialized as {name: 'math', grade: '3.9}
. We can use
touca.add_serializer
to override this default behavior. The following code
results in the same object to be serialized as ['math', 3.9]
:
touca.add_serializer(Course.name, (x: Course) => [x.name, x.grade]);
for (const course of student.courses) {
touca.add_array_element("courses", course);
touca.add_hit_count("number of courses");
}
While our serializer changed the way Course
data is serialized and visualized,
it still preserved both properties of this object. If we like to exclude the
property name
during serialization and limit the comparison to grade
, we
could use (x: Course) => x.grade
instead.
While Touca data capturing functions automatically support objects and custom types, it is possible to override the serialization logic for any given non-primitive data type.
Consider the following definition for a custom class Course
.
public final class Course {
public String name;
public double grade;
public Course(final String name, final double grade) {
this.name = name;
this.grade = grade;
}
}
By default, the SDK serializes objects of this class using by serializing all of
its public properties. This behavior results in object Course("math", 3.9)
to
be serialized as {name: "math", grade: 3.9}
. We can use Touca.addTypeAdapter
to override this default behavior. The following code excludes the property
name
during serialization and limits the comparison to grade
:
Touca.addTypeAdapter(Course.class, course -> course.grade);
for (Course course: student.courses) {
Touca.addArrayElement("courses", course);
Touca.addHitCount("number of courses");
}
It is sufficient to register each serializer once per lifetime of the test application.