.\"
.\"	aegis - project change supervisor
.\"	Copyright (C) 1996, 1999, 2002, 2005-2008 Peter Miller
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 3 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program. If not, see
.\"	<http://www.gnu.org/licenses/>.
.\"
.SH TEST CORRELATIONS
The \[lq]\*(n) -Test -SUGgest\[rq] command may be used to have \*(n)
suggest suitable regression tests for your change, based on the source
files in your change.  This automatically focuses testing effort
to relevant tests, reducing the number of regression tests
necessary to be confident that you have not introduced a bug.
.PP
The test correlations are generated by the \[lq]\*(n)
-Integrate_Pass\[rq] command, which associates each test in the
change with each source file in the change.  Thus, each source
file accumulates a list of tests which have been associated with
it in the past.  This is not as exact as code coverage analysis,
but is a reasonable approximation in practice.
.PP
The
.IR aecp (1)
and
.IR aenf (1)
commands are used to associate files with a change.  While they
do not actively perform the association, these are the files
used by
.IR aeipass (1)
and
.IR aet (1)
to determine which source files are associated with which tests.
.SS Test Correlation Accuracy
Assuming that the testing correlations are accurate and that the
tests are evenly distributed across the function space, there
will be a less than \fI1/number\fP chance that a relevant test
has not been run by the \[lq]\*(n) -Test -SUGgest \fInumber\fP\[rq]
command.  A small amount of noise is added to the test
weighting, so that unexpected things are sometimes tested, and
the same tests are not run every time.
.PP
Test correlation accuracy can be improved by ensuring that:
.TP 2m
\(bu
Each change should be strongly focused, with no gratuitous file
inclusions.  This avoids spurious correlations.
.TP 2m
\(bu
Each item of new functionality should be added in an individual change,
rather than several together.  This strongly correlates tests with
functionality.
.TP 2m
\(bu
Each bug should be fixed in an individual change, rather than several
together.  This strongly correlates tests with functionality.
.TP 2m
\(bu
Test correlations will be lost if files are moved.  This is because
correlations are by name.
.PP
The best way for tests to correlate accurately with source files is when
a change contains a test and exactly those files relating to the
functionality under test.  Too many spurious files will weaken the
usefulness of the testing correlations.