<html>
<title>AspectJ release testing</title>
<body>
<h1>AspectJ release testing</h1>
This describes tests to validate AspectJ before a release.
<u>WARNING<u>: this file is being superceded by
<a href="../build/release-checklist.txt">
../build/release-checklist.txt</a>.
Some tests may be omitted for pre-release distributions, but all
should be run for final releases.
For information on how to build and run tests, see
<a href="../build/readme-build-and-test-aspectj.html">
../build/readme-build-and-test-aspectj.html</a>
and
<a href="readme-tests-module.html">
readme-tests-module.html</a>.
<p>(Most of these can and should be rolled into an Ant script
for automation; until that script is written, this describes
tests and could and/or should be run.)
<p>Before a release, run the following tests using a Java 1.3 VM
(the minimum required by the AspectJ tools):
<ol>
<li>JUnit tests. Run these before the final build
using <code>tests/junitModules.xml</code>
(which runs all the
<code>modules/{module}/testsrc/{module}ModuleTests.java</code>).
<p>
</li>
<li>All compiler tests in <code>tests/ajcTests.xml</code>
and <code>tests/ajcTestsFailing.xml</code>.
Run these before the final build using the test harness,
as follows:
<pre>
cd tests/
java -jar {..}/testing-drivers-all.jar ajcTests.xml -release
</pre>
The <code>-release</code> option skips tests
marked <code>purejava</code> or <code>knownLimitation</code>
and only emits one-line results for each test:
<pre>
PASS one test identifier()
FAIL another test identifier()
...
</pre>
(Use <code>-help</code> on the harness to see the full
definition of the <code>-release</code> alias.)
Save the output
to the appropriate subdirectory of the
<a href="../../releases">org.aspectj/releases</a> directory
with the name
<code>ajcTests-result-{version}.txt</code>.
or <code>ajcTests-result-{version}-emacssym.txt</code>.
<p>
Compare results with a prior release or test run using TestDiffs:
<pre>
set CLASSPATH="{..}/testing-drivers-all.jar"
java org.aspectj.testing.util.TestDiffs {first-run}.txt {second-run}.txt
</pre>
This will generate lists of tests fixed, broken, missing, or
added. For a release, no tests from <code>ajcTests.xml</code>
should be broken, and missing tests (those in the first run absent from the
second run) should be justified (usually the test was
removed as invalid). A test will show up as
missing from the first run and added to the second run if
it is renamed between runs.
For a final release, no test should be <code>FAIL</code> unless it is
deferred (including those from <code>ajcTestsFailing.xml</code>).
<p>
For (at least final) releases, run all relevant variants:
<ul>
<li>With and without <code>-emacssym</code></li>
<li>1.3 and 1.4 VM's</li>
<li>without -release and with purejava tests. While
these may fail, they should not crash the compiler.</li>
</ul>
<li>Examples. Run these on the built/installed release.
The following should build and run the spacewar example:
<pre>
cd {aspectj-install}/doc/examples
{ant 1.5.1} -f build.xml
</pre>
Also run 2-3 other targets from Ant and some examples directly:
<ul>
<li>
The target <code>all</code>
runs all examples, and <code>nonGui</code> runs those
that do not require manual operation;
</li>
<li>The target<code>tracing-bc</code> does bytecode weaving
</li>
<li>The target<code>tracing-adapter-ajc</code> compiles the
tracing example using the <javac> task and the
Ajc compiler adapter.
</li>
<li>
Run the compiled examples in a 1.1 VM
(the minimum required for running AspectJ code).
</li>
</ul>
<p>
This quick test verifies that the
<code>aspectjtools.jar</code> and <code>aspectjrt.jar</code>
are installed and have a matching version, that the examples actually
compile and run, etc.
<p>
</li>
<li>If there are any bugs which are closed with this release
but which do not have an automated test case run using
JUnit or the harness, those bugs should be manually tested
against the release.
<p>
</li>
<li>Any other tests warranted by release objectives.
E.g., make sure it works as expected for any demos or
for any clients (e.g., Emacs, AJDT).
</li>
<li>Compile large open-source Java projects using AspectJ.
</li>
<li>Run the AspectJ compiler against the Jacks test suite.
</li>
<li>Manually step through the
<a href="ajde/script.html">ajde/script.html</a>
on the AspectJ browser.
</ol>
<p>Some failures with past releases to consider checking:
<ul>
<li>debug info not included in .class files</li>
<li>API not included in documentation</li>
<li>Ant variables not filtered into doc files (e.g., ant-tasks.html)</li>
<li>Manual dates not changed in docs or readme</li>
<li>Inconsistent version information between runtime and tools classes</li>
</ul>
</body>
</html>