test2json.go

     1  // Copyright 2017 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package test2json implements conversion of test binary output to JSON.
     6  // It is used by cmd/test2json and cmd/go.
     7  //
     8  // See the cmd/test2json documentation for details of the JSON encoding.
     9  package test2json
    10  
    11  import (
    12  	"bytes"
    13  	"encoding/json"
    14  	"fmt"
    15  	"io"
    16  	"strconv"
    17  	"strings"
    18  	"time"
    19  	"unicode"
    20  	"unicode/utf8"
    21  )
    22  
    23  // Mode controls details of the conversion.
    24  type Mode int
    25  
    26  const (
    27  	Timestamp Mode = 1 << iota // include Time in events
    28  )
    29  
    30  // event is the JSON struct we emit.
    31  type event struct {
    32  	Time        *time.Time `json:",omitempty"`
    33  	Action      string
    34  	Package     string     `json:",omitempty"`
    35  	Test        string     `json:",omitempty"`
    36  	Elapsed     *float64   `json:",omitempty"`
    37  	Output      *textBytes `json:",omitempty"`
    38  	FailedBuild string     `json:",omitempty"`
    39  	Key         string     `json:",omitempty"`
    40  	Value       string     `json:",omitempty"`
    41  	Path        string     `json:",omitempty"`
    42  }
    43  
    44  // textBytes is a hack to get JSON to emit a []byte as a string
    45  // without actually copying it to a string.
    46  // It implements encoding.TextMarshaler, which returns its text form as a []byte,
    47  // and then json encodes that text form as a string (which was our goal).
    48  type textBytes []byte
    49  
    50  func (b textBytes) MarshalText() ([]byte, error) { return b, nil }
    51  
    52  // A Converter holds the state of a test-to-JSON conversion.
    53  // It implements io.WriteCloser; the caller writes test output in,
    54  // and the converter writes JSON output to w.
    55  type Converter struct {
    56  	w          io.Writer  // JSON output stream
    57  	pkg        string     // package to name in events
    58  	mode       Mode       // mode bits
    59  	start      time.Time  // time converter started
    60  	testName   string     // name of current test, for output attribution
    61  	report     []*event   // pending test result reports (nested for subtests)
    62  	result     string     // overall test result if seen
    63  	input      lineBuffer // input buffer
    64  	output     lineBuffer // output buffer
    65  	needMarker bool       // require ^V marker to introduce test framing line
    66  
    67  	// failedBuild is set to the package ID of the cause of a build failure,
    68  	// if that's what caused this test to fail.
    69  	failedBuild string
    70  }
    71  
    72  // inBuffer and outBuffer are the input and output buffer sizes.
    73  // They're variables so that they can be reduced during testing.
    74  //
    75  // The input buffer needs to be able to hold any single test
    76  // directive line we want to recognize, like:
    77  //
    78  //	<many spaces> --- PASS: very/nested/s/u/b/t/e/s/t
    79  //
    80  // If anyone reports a test directive line > 4k not working, it will
    81  // be defensible to suggest they restructure their test or test names.
    82  //
    83  // The output buffer must be >= utf8.UTFMax, so that it can
    84  // accumulate any single UTF8 sequence. Lines that fit entirely
    85  // within the output buffer are emitted in single output events.
    86  // Otherwise they are split into multiple events.
    87  // The output buffer size therefore limits the size of the encoding
    88  // of a single JSON output event. 1k seems like a reasonable balance
    89  // between wanting to avoid splitting an output line and not wanting to
    90  // generate enormous output events.
    91  var (
    92  	inBuffer  = 4096
    93  	outBuffer = 1024
    94  )
    95  
    96  // NewConverter returns a "test to json" converter.
    97  // Writes on the returned writer are written as JSON to w,
    98  // with minimal delay.
    99  //
   100  // The writes to w are whole JSON events ending in \n,
   101  // so that it is safe to run multiple tests writing to multiple converters
   102  // writing to a single underlying output stream w.
   103  // As long as the underlying output w can handle concurrent writes
   104  // from multiple goroutines, the result will be a JSON stream
   105  // describing the relative ordering of execution in all the concurrent tests.
   106  //
   107  // The mode flag adjusts the behavior of the converter.
   108  // Passing ModeTime includes event timestamps and elapsed times.
   109  //
   110  // The pkg string, if present, specifies the import path to
   111  // report in the JSON stream.
   112  func NewConverter(w io.Writer, pkg string, mode Mode) *Converter {
   113  	c := new(Converter)
   114  	*c = Converter{
   115  		w:     w,
   116  		pkg:   pkg,
   117  		mode:  mode,
   118  		start: time.Now(),
   119  		input: lineBuffer{
   120  			b:    make([]byte, 0, inBuffer),
   121  			line: c.handleInputLine,
   122  			part: c.output.write,
   123  		},
   124  		output: lineBuffer{
   125  			b:    make([]byte, 0, outBuffer),
   126  			line: c.writeOutputEvent,
   127  			part: c.writeOutputEvent,
   128  		},
   129  	}
   130  	c.writeEvent(&event{Action: "start"})
   131  	return c
   132  }
   133  
   134  // Write writes the test input to the converter.
   135  func (c *Converter) Write(b []byte) (int, error) {
   136  	c.input.write(b)
   137  	return len(b), nil
   138  }
   139  
   140  // Exited marks the test process as having exited with the given error.
   141  func (c *Converter) Exited(err error) {
   142  	if err == nil {
   143  		if c.result != "skip" {
   144  			c.result = "pass"
   145  		}
   146  	} else {
   147  		c.result = "fail"
   148  	}
   149  }
   150  
   151  // SetFailedBuild sets the package ID that is the root cause of a build failure
   152  // for this test. This will be reported in the final "fail" event's FailedBuild
   153  // field.
   154  func (c *Converter) SetFailedBuild(pkgID string) {
   155  	c.failedBuild = pkgID
   156  }
   157  
   158  const marker = byte(0x16) // ^V
   159  
   160  var (
   161  	// printed by test on successful run.
   162  	bigPass = []byte("PASS")
   163  
   164  	// printed by test after a normal test failure.
   165  	bigFail = []byte("FAIL")
   166  
   167  	// printed by 'go test' along with an error if the test binary terminates
   168  	// with an error.
   169  	bigFailErrorPrefix = []byte("FAIL\t")
   170  
   171  	// an === NAME line with no test name, if trailing spaces are deleted
   172  	emptyName     = []byte("=== NAME")
   173  	emptyNameLine = []byte("=== NAME  \n")
   174  
   175  	updates = [][]byte{
   176  		[]byte("=== RUN   "),
   177  		[]byte("=== PAUSE "),
   178  		[]byte("=== CONT  "),
   179  		[]byte("=== NAME  "),
   180  		[]byte("=== PASS  "),
   181  		[]byte("=== FAIL  "),
   182  		[]byte("=== SKIP  "),
   183  		[]byte("=== ATTR  "),
   184  		[]byte("=== ARTIFACTS "),
   185  	}
   186  
   187  	reports = [][]byte{
   188  		[]byte("--- PASS: "),
   189  		[]byte("--- FAIL: "),
   190  		[]byte("--- SKIP: "),
   191  		[]byte("--- BENCH: "),
   192  	}
   193  
   194  	fourSpace = []byte("    ")
   195  
   196  	skipLinePrefix = []byte("?   \t")
   197  	skipLineSuffix = []byte("\t[no test files]")
   198  )
   199  
   200  // handleInputLine handles a single whole test output line.
   201  // It must write the line to c.output but may choose to do so
   202  // before or after emitting other events.
   203  func (c *Converter) handleInputLine(line []byte) {
   204  	if len(line) == 0 {
   205  		return
   206  	}
   207  	sawMarker := false
   208  	if c.needMarker && line[0] != marker {
   209  		c.output.write(line)
   210  		return
   211  	}
   212  	if line[0] == marker {
   213  		c.output.flush()
   214  		sawMarker = true
   215  		line = line[1:]
   216  	}
   217  
   218  	// Trim is line without \n or \r\n.
   219  	trim := line
   220  	if len(trim) > 0 && trim[len(trim)-1] == '\n' {
   221  		trim = trim[:len(trim)-1]
   222  		if len(trim) > 0 && trim[len(trim)-1] == '\r' {
   223  			trim = trim[:len(trim)-1]
   224  		}
   225  	}
   226  
   227  	// === CONT followed by an empty test name can lose its trailing spaces.
   228  	if bytes.Equal(trim, emptyName) {
   229  		line = emptyNameLine
   230  		trim = line[:len(line)-1]
   231  	}
   232  
   233  	// Final PASS or FAIL.
   234  	if bytes.Equal(trim, bigPass) || bytes.Equal(trim, bigFail) || bytes.HasPrefix(trim, bigFailErrorPrefix) {
   235  		c.flushReport(0)
   236  		c.testName = ""
   237  		c.needMarker = sawMarker
   238  		c.output.write(line)
   239  		if bytes.Equal(trim, bigPass) {
   240  			c.result = "pass"
   241  		} else {
   242  			c.result = "fail"
   243  		}
   244  		return
   245  	}
   246  
   247  	// Special case for entirely skipped test binary: "?   \tpkgname\t[no test files]\n" is only line.
   248  	// Report it as plain output but remember to say skip in the final summary.
   249  	if bytes.HasPrefix(line, skipLinePrefix) && bytes.HasSuffix(trim, skipLineSuffix) && len(c.report) == 0 {
   250  		c.result = "skip"
   251  	}
   252  
   253  	// "=== RUN   "
   254  	// "=== PAUSE "
   255  	// "=== CONT  "
   256  	origLine := line
   257  	ok := false
   258  	indent := 0
   259  	for _, magic := range updates {
   260  		if bytes.HasPrefix(line, magic) {
   261  			ok = true
   262  			break
   263  		}
   264  	}
   265  	if !ok {
   266  		// "--- PASS: "
   267  		// "--- FAIL: "
   268  		// "--- SKIP: "
   269  		// "--- BENCH: "
   270  		// but possibly indented.
   271  		for bytes.HasPrefix(line, fourSpace) {
   272  			line = line[4:]
   273  			indent++
   274  		}
   275  		for _, magic := range reports {
   276  			if bytes.HasPrefix(line, magic) {
   277  				ok = true
   278  				break
   279  			}
   280  		}
   281  	}
   282  
   283  	// Not a special test output line.
   284  	if !ok {
   285  		// Lookup the name of the test which produced the output using the
   286  		// indentation of the output as an index into the stack of the current
   287  		// subtests.
   288  		// If the indentation is greater than the number of current subtests
   289  		// then the output must have included extra indentation. We can't
   290  		// determine which subtest produced this output, so we default to the
   291  		// old behaviour of assuming the most recently run subtest produced it.
   292  		if indent > 0 && indent <= len(c.report) {
   293  			c.testName = c.report[indent-1].Test
   294  		}
   295  		c.output.write(origLine)
   296  		return
   297  	}
   298  
   299  	// Parse out action and test name from "=== ACTION: Name".
   300  	action, name, _ := strings.Cut(string(line[len("=== "):]), " ")
   301  	action = strings.TrimSuffix(action, ":")
   302  	action = strings.ToLower(action)
   303  	name = strings.TrimSpace(name)
   304  
   305  	e := &event{Action: action}
   306  	if line[0] == '-' { // PASS or FAIL report
   307  		// Parse out elapsed time.
   308  		if i := strings.Index(name, " ("); i >= 0 {
   309  			if strings.HasSuffix(name, "s)") {
   310  				t, err := strconv.ParseFloat(name[i+2:len(name)-2], 64)
   311  				if err == nil {
   312  					if c.mode&Timestamp != 0 {
   313  						e.Elapsed = &t
   314  					}
   315  				}
   316  			}
   317  			name = name[:i]
   318  		}
   319  		if len(c.report) < indent {
   320  			// Nested deeper than expected.
   321  			// Treat this line as plain output.
   322  			c.output.write(origLine)
   323  			return
   324  		}
   325  		// Flush reports at this indentation level or deeper.
   326  		c.needMarker = sawMarker
   327  		c.flushReport(indent)
   328  		e.Test = name
   329  		c.testName = name
   330  		c.report = append(c.report, e)
   331  		c.output.write(origLine)
   332  		return
   333  	}
   334  	switch action {
   335  	case "artifacts":
   336  		name, e.Path, _ = strings.Cut(name, " ")
   337  	case "attr":
   338  		var rest string
   339  		name, rest, _ = strings.Cut(name, " ")
   340  		e.Key, e.Value, _ = strings.Cut(rest, " ")
   341  	}
   342  	// === update.
   343  	// Finish any pending PASS/FAIL reports.
   344  	c.needMarker = sawMarker
   345  	c.flushReport(0)
   346  	c.testName = name
   347  
   348  	if action == "name" {
   349  		// This line is only generated to get c.testName right.
   350  		// Don't emit an event.
   351  		return
   352  	}
   353  
   354  	if action == "pause" {
   355  		// For a pause, we want to write the pause notification before
   356  		// delivering the pause event, just so it doesn't look like the test
   357  		// is generating output immediately after being paused.
   358  		c.output.write(origLine)
   359  	}
   360  	c.writeEvent(e)
   361  	if action != "pause" {
   362  		c.output.write(origLine)
   363  	}
   364  
   365  	return
   366  }
   367  
   368  // flushReport flushes all pending PASS/FAIL reports at levels >= depth.
   369  func (c *Converter) flushReport(depth int) {
   370  	c.testName = ""
   371  	for len(c.report) > depth {
   372  		e := c.report[len(c.report)-1]
   373  		c.report = c.report[:len(c.report)-1]
   374  		c.writeEvent(e)
   375  	}
   376  }
   377  
   378  // Close marks the end of the go test output.
   379  // It flushes any pending input and then output (only partial lines at this point)
   380  // and then emits the final overall package-level pass/fail event.
   381  func (c *Converter) Close() error {
   382  	c.input.flush()
   383  	c.output.flush()
   384  	if c.result != "" {
   385  		e := &event{Action: c.result}
   386  		if c.mode&Timestamp != 0 {
   387  			dt := time.Since(c.start).Round(1 * time.Millisecond).Seconds()
   388  			e.Elapsed = &dt
   389  		}
   390  		if c.result == "fail" {
   391  			e.FailedBuild = c.failedBuild
   392  		}
   393  		c.writeEvent(e)
   394  	}
   395  	return nil
   396  }
   397  
   398  // writeOutputEvent writes a single output event with the given bytes.
   399  func (c *Converter) writeOutputEvent(out []byte) {
   400  	c.writeEvent(&event{
   401  		Action: "output",
   402  		Output: (*textBytes)(&out),
   403  	})
   404  }
   405  
   406  // writeEvent writes a single event.
   407  // It adds the package, time (if requested), and test name (if needed).
   408  func (c *Converter) writeEvent(e *event) {
   409  	e.Package = c.pkg
   410  	if c.mode&Timestamp != 0 {
   411  		t := time.Now()
   412  		e.Time = &t
   413  	}
   414  	if e.Test == "" {
   415  		e.Test = c.testName
   416  	}
   417  	js, err := json.Marshal(e)
   418  	if err != nil {
   419  		// Should not happen - event is valid for json.Marshal.
   420  		fmt.Fprintf(c.w, "testjson internal error: %v\n", err)
   421  		return
   422  	}
   423  	js = append(js, '\n')
   424  	c.w.Write(js)
   425  }
   426  
   427  // A lineBuffer is an I/O buffer that reacts to writes by invoking
   428  // input-processing callbacks on whole lines or (for long lines that
   429  // have been split) line fragments.
   430  //
   431  // It should be initialized with b set to a buffer of length 0 but non-zero capacity,
   432  // and line and part set to the desired input processors.
   433  // The lineBuffer will call line(x) for any whole line x (including the final newline)
   434  // that fits entirely in cap(b). It will handle input lines longer than cap(b) by
   435  // calling part(x) for sections of the line. The line will be split at UTF8 boundaries,
   436  // and the final call to part for a long line includes the final newline.
   437  type lineBuffer struct {
   438  	b    []byte       // buffer
   439  	mid  bool         // whether we're in the middle of a long line
   440  	line func([]byte) // line callback
   441  	part func([]byte) // partial line callback
   442  }
   443  
   444  // write writes b to the buffer.
   445  func (l *lineBuffer) write(b []byte) {
   446  	for len(b) > 0 {
   447  		// Copy what we can into l.b.
   448  		m := copy(l.b[len(l.b):cap(l.b)], b)
   449  		l.b = l.b[:len(l.b)+m]
   450  		b = b[m:]
   451  
   452  		// Process lines in l.b.
   453  		i := 0
   454  		for i < len(l.b) {
   455  			j, w := indexEOL(l.b[i:])
   456  			if j < 0 {
   457  				if !l.mid {
   458  					if j := bytes.IndexByte(l.b[i:], '\t'); j >= 0 {
   459  						if isBenchmarkName(bytes.TrimRight(l.b[i:i+j], " ")) {
   460  							l.part(l.b[i : i+j+1])
   461  							l.mid = true
   462  							i += j + 1
   463  						}
   464  					}
   465  				}
   466  				break
   467  			}
   468  			e := i + j + w
   469  			if l.mid {
   470  				// Found the end of a partial line.
   471  				l.part(l.b[i:e])
   472  				l.mid = false
   473  			} else {
   474  				// Found a whole line.
   475  				l.line(l.b[i:e])
   476  			}
   477  			i = e
   478  		}
   479  
   480  		// Whatever's left in l.b is a line fragment.
   481  		if i == 0 && len(l.b) == cap(l.b) {
   482  			// The whole buffer is a fragment.
   483  			// Emit it as the beginning (or continuation) of a partial line.
   484  			t := trimUTF8(l.b)
   485  			l.part(l.b[:t])
   486  			l.b = l.b[:copy(l.b, l.b[t:])]
   487  			l.mid = true
   488  		}
   489  
   490  		// There's room for more input.
   491  		// Slide it down in hope of completing the line.
   492  		if i > 0 {
   493  			l.b = l.b[:copy(l.b, l.b[i:])]
   494  		}
   495  	}
   496  }
   497  
   498  // indexEOL finds the index of a line ending,
   499  // returning its position and output width.
   500  // A line ending is either a \n or the empty string just before a ^V not beginning a line.
   501  // The output width for \n is 1 (meaning it should be printed)
   502  // but the output width for ^V is 0 (meaning it should be left to begin the next line).
   503  func indexEOL(b []byte) (pos, wid int) {
   504  	for i, c := range b {
   505  		if c == '\n' {
   506  			return i, 1
   507  		}
   508  		if c == marker && i > 0 { // test -v=json emits ^V at start of framing lines
   509  			return i, 0
   510  		}
   511  	}
   512  	return -1, 0
   513  }
   514  
   515  // flush flushes the line buffer.
   516  func (l *lineBuffer) flush() {
   517  	if len(l.b) > 0 {
   518  		// Must be a line without a \n, so a partial line.
   519  		l.part(l.b)
   520  		l.b = l.b[:0]
   521  	}
   522  }
   523  
   524  var benchmark = []byte("Benchmark")
   525  
   526  // isBenchmarkName reports whether b is a valid benchmark name
   527  // that might appear as the first field in a benchmark result line.
   528  func isBenchmarkName(b []byte) bool {
   529  	if !bytes.HasPrefix(b, benchmark) {
   530  		return false
   531  	}
   532  	if len(b) == len(benchmark) { // just "Benchmark"
   533  		return true
   534  	}
   535  	r, _ := utf8.DecodeRune(b[len(benchmark):])
   536  	return !unicode.IsLower(r)
   537  }
   538  
   539  // trimUTF8 returns a length t as close to len(b) as possible such that b[:t]
   540  // does not end in the middle of a possibly-valid UTF-8 sequence.
   541  //
   542  // If a large text buffer must be split before position i at the latest,
   543  // splitting at position trimUTF(b[:i]) avoids splitting a UTF-8 sequence.
   544  func trimUTF8(b []byte) int {
   545  	// Scan backward to find non-continuation byte.
   546  	for i := 1; i < utf8.UTFMax && i <= len(b); i++ {
   547  		if c := b[len(b)-i]; c&0xc0 != 0x80 {
   548  			switch {
   549  			case c&0xe0 == 0xc0:
   550  				if i < 2 {
   551  					return len(b) - i
   552  				}
   553  			case c&0xf0 == 0xe0:
   554  				if i < 3 {
   555  					return len(b) - i
   556  				}
   557  			case c&0xf8 == 0xf0:
   558  				if i < 4 {
   559  					return len(b) - i
   560  				}
   561  			}
   562  			break
   563  		}
   564  	}
   565  	return len(b)
   566  }
   567
View as plain text