pkg/job/reporting.go

// Copyright (c) Facebook, Inc. and its affiliates.
//
// This source code is licensed under the MIT license found in the
// LICENSE file in the root directory of this source tree.

package job

import (
	"bytes"
	"encoding/json"
	"time"

	"github.com/facebookincubator/contest/pkg/event/testevent"
	"github.com/facebookincubator/contest/pkg/types"
	"github.com/facebookincubator/contest/pkg/xcontext"
)

// Reporting is the configuration section that determines how to report the
// results. It is divided in run reporting and final reporting. The run
// reporters are called when each test run is completed, while the final
// reporters are called once at the end of the whole set of runs is completed.
// The final reporters are optional.
// If the job is continuous (e.g. run indefinitely), the final reporters are
// only called if the job is interrupted.
type Reporting struct {
	RunReporters   []ReporterConfig
	FinalReporters []ReporterConfig
}

// ReporterConfig is the configuration of a specific reporter, either a run
// reporter or a final reporter.
type ReporterConfig struct {
	Name       string
	Parameters json.RawMessage
}

// ReporterFactory is a type representing a function which builds a Reporter object
type ReporterFactory func() Reporter

// ReporterLoader is a type representing a function which returns all the
// needed things to be able to load a Reporter object
type ReporterLoader func() (string, ReporterFactory)

// Reporter is an interface used to implement logic which calculates the result
// of a Job. The result is conveyed via a JobReport object.
type Reporter interface {
	ValidateRunParameters([]byte) (interface{}, error)
	ValidateFinalParameters([]byte) (interface{}, error)

	Name() string

	RunReport(ctx xcontext.Context, parameters interface{}, runStatus *RunStatus, ev testevent.Fetcher) (bool, interface{}, error)
	FinalReport(ctx xcontext.Context, parameters interface{}, runStatuses []RunStatus, ev testevent.Fetcher) (bool, interface{}, error)
}

// ReporterBundle bundles the selected Reporter together with its parameters
// based on the content of the job descriptor
type ReporterBundle struct {
	Reporter   Reporter
	Parameters interface{}
}

// Report wraps the information of a run report or a final report.
type Report struct {
	JobID        types.JobID
	RunID        types.RunID `json:"RunID,omitempty"` // 0 for a final report
	ReporterName string
	ReportTime   time.Time
	Success      bool
	Data         interface{}
}

// JobReport represents the whole job report generated by ConTest.
type JobReport struct {
	JobID types.JobID
	// JobReport represents the report generated by the plugin selected in the job descriptor
	RunReports   [][]*Report
	FinalReports []*Report
}

// ToJSON marshals the report into JSON, disabling HTML escaping
func (r *Report) ToJSON() ([]byte, error) {
	buffer := &bytes.Buffer{}
	encoder := json.NewEncoder(buffer)
	encoder.SetEscapeHTML(false)
	err := encoder.Encode(r.Data)
	return buffer.Bytes(), err
}