This is an automated email from the ASF dual-hosted git repository.
joshtynjala pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/royale-asjs.git
The following commit(s) were added to refs/heads/develop by this push:
new 5a38c10 RoyaleUnit: asdocs and metadata constants
5a38c10 is described below
commit 5a38c10fd4146ee3c5912d089c65deec3c30c0ad
Author: Josh Tynjala <[email protected]>
AuthorDate: Tue Oct 8 10:16:07 2019 -0700
RoyaleUnit: asdocs and metadata constants
---
.../org/apache/royale/test/async/AsyncLocator.as | 32 ++++++++++++++++++
.../org/apache/royale/test/async/IAsyncHandler.as | 3 ++
.../org/apache/royale/test/listeners/CIListener.as | 4 +++
.../org/apache/royale/test/runners/ITestRunner.as | 7 ++++
.../apache/royale/test/runners/MetadataRunner.as | 22 ++++++++++---
.../org/apache/royale/test/runners/ParentRunner.as | 4 ++-
.../org/apache/royale/test/runners/SuiteRunner.as | 9 +++--
.../org/apache/royale/test/runners/TestMetadata.as | 38 +++++++++++++++++++---
.../royale/test/runners/notification/Failure.as | 16 +++++++--
9 files changed, 121 insertions(+), 14 deletions(-)
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/AsyncLocator.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/AsyncLocator.as
index aa0721f..330d835 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/AsyncLocator.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/AsyncLocator.as
@@ -31,8 +31,14 @@ package org.apache.royale.test.async
COMPILE::SWF
public class AsyncLocator
{
+ /**
+ * @private
+ */
private static var handlers:Dictionary;
+ /**
+ * Called by the test runner before an async test has started.
+ */
public static function setAsyncHandlerForTest(test:Object,
handler:IAsyncHandler):void
{
if(!handlers)
@@ -42,6 +48,10 @@ package org.apache.royale.test.async
handlers[test] = handler;
}
+ /**
+ * Returns the current async handler for the specified test, or
throws
+ * an exception if there is none.
+ */
public static function
getAsyncHandlerForTest(test:Object):IAsyncHandler
{
if(!handlers || !hasAsyncHandlerForTest(test))
@@ -51,6 +61,9 @@ package org.apache.royale.test.async
return handlers[test];
}
+ /**
+ * Called by the test runner after an async test has completed.
+ */
public static function
clearAsyncHandlerForTest(test:Object):void
{
if(!handlers || !hasAsyncHandlerForTest(test))
@@ -60,6 +73,9 @@ package org.apache.royale.test.async
delete handlers[test];
}
+ /**
+ * Indicates if there is an async handler for the specified
test.
+ */
public static function
hasAsyncHandlerForTest(test:Object):Boolean
{
return test in handlers;
@@ -72,13 +88,23 @@ package org.apache.royale.test.async
COMPILE::JS
public class AsyncLocator
{
+ /**
+ * @private
+ */
private static var handlers:Map = new Map();
+ /**
+ * Called by the test runner before an async test has started.
+ */
public static function setAsyncHandlerForTest(test:Object,
handler:IAsyncHandler):void
{
handlers.set(test, handler);
}
+ /**
+ * Returns the current async handler for the specified test, or
throws
+ * an exception if there is none.
+ */
public static function
getAsyncHandlerForTest(test:Object):IAsyncHandler
{
if(!handlers || !hasAsyncHandlerForTest(test))
@@ -88,6 +114,9 @@ package org.apache.royale.test.async
return IAsyncHandler(handlers.get(test));
}
+ /**
+ * Called by the test runner after an async test has completed.
+ */
public static function
clearAsyncHandlerForTest(test:Object):void
{
if(!handlers || !hasAsyncHandlerForTest(test))
@@ -97,6 +126,9 @@ package org.apache.royale.test.async
handlers.delete(test);
}
+ /**
+ * Indicates if there is an async handler for the specified
test.
+ */
public static function
hasAsyncHandlerForTest(test:Object):Boolean
{
return handlers.has(test);
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/IAsyncHandler.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/IAsyncHandler.as
index 86652b1..cd3f8bb 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/IAsyncHandler.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/async/IAsyncHandler.as
@@ -28,6 +28,9 @@ package org.apache.royale.test.async
*/
function get bodyExecuting():Boolean;
+ /**
+ * Sets the function to call after a delay.
+ */
function asyncHandler(eventListener:Function, delay:int):void;
}
}
\ No newline at end of file
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/listeners/CIListener.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/listeners/CIListener.as
index 4c69b3c..a21d4c9 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/listeners/CIListener.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/listeners/CIListener.as
@@ -34,6 +34,10 @@ package org.apache.royale.test.listeners
import flash.net.XMLSocket;
}
+ /**
+ * Communicates with a socket server to integrate RoyaleUnit tests with
a
+ * build system, such as <a
href="https://apache.github.io/royale-docs/testing/royaleunit/run-unit-tests-with-ant";>Apache
Ant</a>.
+ */
public class CIListener extends EventDispatcher implements
IAsyncStartupRunListener
{
/**
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ITestRunner.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ITestRunner.as
index 9348d2c..c44e9f3 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ITestRunner.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ITestRunner.as
@@ -20,6 +20,13 @@ package org.apache.royale.test.runners
{
import org.apache.royale.test.runners.notification.IRunNotifier;
+ /**
+ * An interface for test runner implementations, such as
+ * <code>MetadataRunner</code> and <code>SuiteRunner</code>.
+ *
+ * @see org.apache.royale.test.runners.MetadataRunner
+ * @see org.apache.royale.test.runners.SuiteRunner
+ */
public interface ITestRunner
{
/**
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/MetadataRunner.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/MetadataRunner.as
index 7b39957..53e192f 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/MetadataRunner.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/MetadataRunner.as
@@ -44,9 +44,21 @@ package org.apache.royale.test.runners
* <li>Tests with <code>[Ignore]</code> metdata should be ignored
(skipped).</li>
* <li>Methods with <code>[Before]</code> metadata are run before every
individual test.</li>
* <li>Methods with <code>[After]</code> metadata are run after every
individual test.</li>
- * <li>Methods with <code>[BeforeClass]</code> metadata are run one
time, before the first test.</li>
- * <li>Methods with <code>[AfterClass]</code> metadata are run one
time, after the final test.</li>
+ * <li>Static methods with <code>[BeforeClass]</code> metadata are run
one time, before the first test.</li>
+ * <li>Static methods with <code>[AfterClass]</code> metadata are run
one time, after the final test.</li>
* </ul>
+ *
+ * <p>To test asynchronous functionality, add the <code>async</code>
+ * modifier to the <code>[Test]</code> metadata, and use the static
methods
+ * on the <code>org.apache.royale.test.async.Async</code> class to set
up a
+ * context for testing asynchronously.</p>
+ *
+ * <p>By default, asynchronous tests fail if they do not complete
within 500
+ * milliseconds. Set the <code>timeout</code> modifier on the
+ * <code>[Test]</code> metadata to customize this duration (measured in
+ * milliseconds).</p>
+ *
+ * @see org.apache.royale.test.async.Async
*/
public class MetadataRunner implements ITestRunner
{
@@ -441,9 +453,9 @@ package org.apache.royale.test.runners
qualifiedName += lastPart;
testName = qualifiedName + "." +
method.name;
testFunction = _target[method.name];
- if(testTag.getArgsByKey("async").length
> 0)
+
if(testTag.getArgsByKey(TestMetadata.TEST__ASYNC).length > 0)
{
- var timeoutArgs:Array =
testTag.getArgsByKey("timeout");
+ var timeoutArgs:Array =
testTag.getArgsByKey(TestMetadata.TEST__TIMEOUT);
if(timeoutArgs.length > 0)
{
asyncTimeout =
parseFloat(timeoutArgs[0].value);
@@ -453,7 +465,7 @@ package org.apache.royale.test.runners
asyncTimeout =
DEFAULT_ASYNC_TIMEOUT;
}
}
- var expectedArgs:Array =
testTag.getArgsByKey("expected");
+ var expectedArgs:Array =
testTag.getArgsByKey(TestMetadata.TEST__EXPECTED);
if(expectedArgs.length > 0)
{
expected =
expectedArgs[0].value;
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ParentRunner.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ParentRunner.as
index 53c03eb..c9bb9ab 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ParentRunner.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/ParentRunner.as
@@ -38,7 +38,9 @@ package org.apache.royale.test.runners
/**
* Provides a base implementation of a runner with children, and
intended to
- * be subclassed.
+ * be subclassed, similar to <code>SuiteRunner</code>.
+ *
+ * @see org.apache.royale.test.runners.SuiteRunner
*/
public class ParentRunner implements ITestRunner
{
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/SuiteRunner.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/SuiteRunner.as
index b5155c9..151d72b 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/SuiteRunner.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/SuiteRunner.as
@@ -25,8 +25,13 @@ package org.apache.royale.test.runners
import org.apache.royale.reflection.getQualifiedClassName;
/**
- * A runner for test suites. Suites should be annotated with
- * <code>[Suite]</code> and <code>[RunWith]</code> metadata.
+ * A runner for test suites.
+ *
+ * <p>Test suites should be annotated with <code>[Suite]</code> and
+ * <code>[RunWith("org.apache.royale.test.runners.SuiteRunner")]</code>
+ * metadata. To add test classes to the suite, define a public variable
for
+ * each class, using the class as the variable type. You may also add
other
+ * suite classes in the same way.</p>
*/
public class SuiteRunner extends ParentRunner implements ITestRunner
{
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/TestMetadata.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/TestMetadata.as
index cf60871..b589fd2 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/TestMetadata.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/TestMetadata.as
@@ -19,8 +19,11 @@
package org.apache.royale.test.runners
{
/**
- * @private
- * Metadata used by tests.
+ * Metadata name constants used by <code>MetadataRunner</code> and
+ * <code>SuiteRunner</code>.
+ *
+ * @see org.apache.royale.test.runners.MetadataRunner
+ * @see org.apache.royale.test.runners.SuiteRunner
*/
internal class TestMetadata
{
@@ -30,6 +33,23 @@ package org.apache.royale.test.runners
public static const TEST:String = "Test";
/**
+ * Indicates that a <code>[Test]</code> method is asyncronous.
+ */
+ public static const TEST__ASYNC:String = "async";
+
+ /**
+ * Indicates that an asynchronous <code>[Test]</code> method
has a
+ * custom timeout.
+ */
+ public static const TEST__TIMEOUT:String = "timeout";
+
+ /**
+ * Indicates that an <code>[Test]</code> method has an expected
+ * exception type.
+ */
+ public static const TEST__EXPECTED:String = "expected";
+
+ /**
* Indicates that a <code>[Test]</code> method should be
skipped.
*/
public static const IGNORE:String = "Ignore";
@@ -57,10 +77,20 @@ package org.apache.royale.test.runners
public static const AFTER_CLASS:String = "AfterClass";
/**
+ * Indicates that a class is a test suite. Must be combined with
+ * <code>[RunWith]</code>.
+ *
+ * <pre><code>[Suite]
+ * [RunWith("org.apache.test.runners.SuiteRunner")]</code></pre>
+ */
+ public static const SUITE:String = "Suite";
+
+ /**
* Indicates which <code>ITestRunner</code> should be used to
run the
- * tests in the class.
+ * tests in the class. Must be combined with
<code>[Suite]</code>.
*
- *
<pre><code>[RunWith("org.apache.test.runners.SuiteRunner")]</code></pre>
+ * <pre><code>[Suite]
+ * [RunWith("org.apache.test.runners.SuiteRunner")]</code></pre>
*/
public static const RUN_WITH:String = "RunWith";
}
diff --git
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/notification/Failure.as
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/notification/Failure.as
index 3c53f76..2570238 100644
---
a/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/notification/Failure.as
+++
b/frameworks/projects/RoyaleUnit/src/main/royale/org/apache/royale/test/runners/notification/Failure.as
@@ -18,8 +18,14 @@
////////////////////////////////////////////////////////////////////////////////
package org.apache.royale.test.runners.notification
{
+ /**
+ * The result of a failed test.
+ */
public class Failure
{
+ /**
+ * Constructor.
+ */
public function Failure(description:String, exception:Error)
{
_description = description;
@@ -61,20 +67,26 @@ package org.apache.royale.test.runners.notification
return _exception;
}
+ /**
+ * @private
+ */
protected var _stackTrace:String = null;
/**
- * Convenience method.
+ * The exception's stack trace.
*/
public function get stackTrace():String
{
return _stackTrace;
}
+ /**
+ * @private
+ */
protected var _message:String = null;
/**
- * Convenience method.
+ * The exception's message.
*/
public function get message():String
{
