{{TableOfContents}}
= NAME =
split_output_per_testcase

= SYNOPSIS =
 * split_output_per_testcase(regex, measurements, info_follows_regex)

= DESCRIPTION =
This function splits the test log into individual files corresponding
to data from each testcase in the test results.

It scans the test log using the provided python regular expression,
and collects lines from the test log that are either before or after
the lines that match the regular expression, and puts groups of lines
into separate files, assigning each group of lines to each testcase
in the measurements list.

These files are referenced by the HTML generator for tables
that appear in the Jenkins interface for the job related to this run.
Thus, the user can click on a link in the HTML table and see
the text for just that test case.

See the output for Functional.jpeg for an example.

== Arguments ==
This function takes 2 mandatory arguments and one optional one.
 * regex - is a python regular expression string used to identify the testcase result data line
 * measurements - is the list of testcase results
 * (optional) info_follows_regex - if true, indicates that the data lines following a match should be used, rather than the data lines preceding the match.

Regex and measurements are usually the same as used with the
[[parser_func_process|process]] function.

== Description of splitting ==
Regex is used to scan through the testlog and find matching lines for
each testcase.

Here is an example of standard formatting:
{{{
  start lines
  data1
  more data1
  TEST 1 PASS
  data2
  data2 foo bar
  TEST 2 FAIL
  more lines
}}}

In this case, if the regex was "TEST (\d+) (.*)$"
the line would be split into the groups:
{{{
  start lines
  more data1
  TEST 1 PASS
}}}
and
{{{
  data2
  data2 foo bar
  TEST 2 FAIL
}}}

These would be referenced as testcase "test1" and testcase "test2", in
the json file (if that's how the parser labeled them - which is what the example below does).

Note that the groups of output from the log are assigned to testcases
by matching the corresponding position in the list of testcases in the
measurements data structure (which is a python list).
That is, the block of text is assigned to the first testcase listed
in measurements; the second block of text to the second testcase, etc.

By default, the data lines '''preceding''' a matching result line are coalesced
into the block of lines for that testcase.  However, some programs
may format their data with the data '''following''' the result line.
In this case, the argument info_follows_regex argument should be set
to True.



= EXAMPLES =
Here is an example usage of split_output_per_testcase:
{{{#!YellowBox
regex_string = '^TEST-(\d+) (.*)$'
matches = plib.parse_log(regex_string)

if matches:
    for m in matches:
        measurements['default.test' + m[0]] = 'PASS' if m[1] == 'OK' else 'FAIL'

# split the output for each testcase
plib.split_output_per_testcase(regex_string, measurements)
}}}


= ENVIRONMENT =
The "common.py" module uses the following environment variables, to find the test log path
 * FUEGO_RW
 * NODE_NAME
 * TESTDIR
 * TESTSPEC
 * BUILD_NUMBER
 * BUILD_ID

= OUTPUT =
split_output_per_testcase makes a directory called 'result' in the log
directory for the run, and populates it with a directory per
test set. Inside each test set directory is a directory called
"outputs", with a file per testcase (using the testcase name as
the file name, suffixed with ".log" inside that.

Note: test_start.log may contain information that precedes the first
test case, and test_end.log may contain information that follows the
last test case.

= RETURN =
Nothing.

= SOURCE =
Located in ''scripts/parser/common.py''

= SEE ALSO =
 * [[parser.py]], [[parser_func_process|process]], [[Parser module API]]