You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by jo...@apache.org on 2019/06/28 22:53:50 UTC
[royale-docs] branch master updated: some basic docs for RoyaleUnit
This is an automated email from the ASF dual-hosted git repository.
joshtynjala pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new ae12239 some basic docs for RoyaleUnit
ae12239 is described below
commit ae12239d627d6fd7019d7345d429994ad48cf251
Author: Josh Tynjala <jo...@bowlerhat.dev>
AuthorDate: Fri Jun 28 15:53:36 2019 -0700
some basic docs for RoyaleUnit
---
_data/toc.json | 19 ++++
testing.md | 27 ++++++
testing/royaleunit.md | 32 ++++++
testing/royaleunit/create-a-unit-test.md | 135 ++++++++++++++++++++++++++
testing/royaleunit/metadata.md | 66 +++++++++++++
testing/royaleunit/run-unit-tests-with-ant.md | 93 ++++++++++++++++++
6 files changed, 372 insertions(+)
diff --git a/_data/toc.json b/_data/toc.json
index 799d78f..6d7b065 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -170,6 +170,25 @@
]
}
]
+ },
+ {
+ "path": "testing.md",
+ "children": [
+ {
+ "path": "testing/royaleunit.md",
+ "children": [
+ {
+ "path": "testing/royaleunit/create-a-unit-test.md"
+ },
+ {
+ "path": "testing/royaleunit/run-unit-tests-with-ant.md"
+ },
+ {
+ "path": "testing/royaleunit/metadata.md"
+ }
+ ]
+ }
+ ]
}
]
}
\ No newline at end of file
diff --git a/testing.md b/testing.md
new file mode 100644
index 0000000..ba74598
--- /dev/null
+++ b/testing.md
@@ -0,0 +1,27 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Testing
+---
+
+# Testing with Apache Royale
+
+Methods for testing Apache Royale projects
+
+## Unit tests
+
+Apache Royale includes the [RoyaleUnit](testing/royaleunit.html) library for unit testing.
\ No newline at end of file
diff --git a/testing/royaleunit.md b/testing/royaleunit.md
new file mode 100644
index 0000000..507f73c
--- /dev/null
+++ b/testing/royaleunit.md
@@ -0,0 +1,32 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: RoyaleUnit
+---
+
+# RoyaleUnit
+
+A unit testing library for Apache Royale
+
+## Tutorials
+
+* [Create a unit test](testing/royaleunit/create-a-unit-test.html)
+* [Run unit tests with Apache Ant](testing/royaleunit/run-unit-tests-with-ant.html)
+
+## Reference
+
+* [Metadata](testing/royaleunit/metadata.html)
\ No newline at end of file
diff --git a/testing/royaleunit/create-a-unit-test.md b/testing/royaleunit/create-a-unit-test.md
new file mode 100644
index 0000000..40b9000
--- /dev/null
+++ b/testing/royaleunit/create-a-unit-test.md
@@ -0,0 +1,135 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Create a unit test
+---
+
+# Create a unit test
+
+An example of creating unit tests with RoyaleUnit
+
+## Test cases
+
+A test case is a class that defines a collection of tests. Each test is written as a method of a class. Each test method should be marked with [`[Test]` metadata](testing/royaleunit/metadata.html#test).
+
+```actionscript
+package com.example
+{
+ import org.apache.royale.test.Assert;
+
+ public class MyFirstTests
+ {
+ [Test]
+ public function testSimpleAdd():void
+ {
+ var result:Number = 2 + 3;
+ Assert.assertEquals(result, 5);
+ }
+
+ [Test]
+ public function testSimpleSubtract():void
+ {
+ var result:Number = 6 - 4;
+ Assert.assertEquals(result, 2);
+ }
+ }
+}
+```
+
+Each test method should be marked with [`[Test]` metadata](testing/royaleunit/metadata.html#test):
+
+```actionscript
+[Test]
+public function testSimpleAdd():void
+```
+
+The `org.apache.royale.test.Assert` class defines a number of assertion methods that may be useful for testing. In this case, use `assertEquals()` to compare two values:
+
+```actionscript
+Assert.assertEquals(result, 5);
+```
+
+If the value of the `result` variable is not equal to `5`, the test will fail.
+
+## Run unit tests
+
+Create a simple Apache Royale application and name it *MyTests.mxml*:
+
+```mxml
+<?xml version="1.0" encoding="utf-8"?>
+<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
+ xmlns:js="library://ns.apache.org/royale/basic"
+ xmlns:test="org.apache.royale.test.*"
+ applicationComplete="runTests()">
+ <fx:Declarations>
+ <test:RoyaleUnitCore id="core"/>
+ </fx:Declarations>
+ <fx:Script>
+ <![CDATA[
+ import org.apache.royale.test.listeners.TraceListener;
+ import com.example.MyFirstTests;
+
+ public function runTests():void
+ {
+ core.addListener(new TraceListener());
+ core.runClasses(MyFirstTests);
+ }
+
+ ]]>
+ </fx:Script>
+ <js:valuesImpl>
+ <js:SimpleValuesImpl values="[]"/>
+ </js:valuesImpl>
+</js:Application>
+```
+
+Use an instance of the `RoyaleUnitCore` class to run unit tests:
+
+```mxml
+<test:RoyaleUnitCore id="core"/>
+```
+
+> Notice the `test` namespace using the `org.apache.royale.test.*` package where the `RoyaleUnitCore` class is defined.
+
+The `TraceListener` class tells `RoyaleUnitCore` displays the test results in the debug console:
+
+```actionscript
+core.addListener(new TraceListener());
+```
+
+Pass one or more test classes to the `runClasses()` method of the `RoyaleUnitCore` instance:
+
+```actionscript
+core.runClasses(MyFirstTests);
+```
+
+Compile this application and run it using a debugger to see the results of the tests.
+
+```sh
+mxmlc -keep-as3-metadata+=Test MyTests.mxml
+```
+
+> Don't forget to tell the compiler to keep any [RoyaleUnit metadata](testing/royaleunit/metadata.html) that is used in the application. In this case, only `[Test]` metadata is used, but several other tags are available.
+
+The debug console output should look similar to the following:
+
+```
+com.example::MyFirstTests.testSimpleAdd .
+com.example::MyFirstTests.testSimpleSubtract .
+Time: 0.346
+OK (2 tests)
+```
\ No newline at end of file
diff --git a/testing/royaleunit/metadata.md b/testing/royaleunit/metadata.md
new file mode 100644
index 0000000..da424e2
--- /dev/null
+++ b/testing/royaleunit/metadata.md
@@ -0,0 +1,66 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Metadata
+---
+
+# RoyaleUnit metadata
+
+Metadata tags for defining unit tests with RoyaleUnit
+
+The following ActionScript metadata tags may be used with RoyaleUnit test classes:
+
+* [After](testing/royaleunit/metadata.html#after)
+* [AfterClass](testing/royaleunit/metadata.html#afterclass)
+* [Before](testing/royaleunit/metadata.html#before)
+* [BeforeClass](testing/royaleunit/metadata.html#beforeclass)
+* [Ignore](testing/royaleunit/metadata.html#ignore)
+* [RunWith](testing/royaleunit/metadata.html#runwith)
+* [Suite](testing/royaleunit/metadata.html#suite)
+* [Test](testing/royaleunit/metadata.html#test)
+
+## After
+
+Specify a method to run after each test in this class.
+
+## AfterClass
+
+Specify a method to run one time, after all tests have completed in this class.
+
+## Before
+
+Specify a method to run before each test in this class.
+
+## BeforeClass
+
+Specify a method to run one time, before any tests have run in this class.
+
+## Ignore
+
+Specify that a specific test method should not run.
+
+## RunWith
+
+Specify the runner to be used with a specific test suite. Should be combined with [`[Suite]` metadata](testing/royaleunit/metadata.html#suite) metadata.
+
+## Suite
+
+Specify that a class is a test suite. Should be combined with Should be combined with [`[RunWith]` metadata](testing/royaleunit/metadata.html#runwith).
+
+## Test
+
+Specify that a method is a test that should be run.
\ No newline at end of file
diff --git a/testing/royaleunit/run-unit-tests-with-ant.md b/testing/royaleunit/run-unit-tests-with-ant.md
new file mode 100644
index 0000000..46895aa
--- /dev/null
+++ b/testing/royaleunit/run-unit-tests-with-ant.md
@@ -0,0 +1,93 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Run unit tests with Apache Ant
+---
+
+# Run unit tests with Apache Ant
+
+Add a custom task for RoyaleUnit to your Apache Ant build files
+
+## Activate the RoyaleUnit Ant task
+
+First, we need to add a `<taskdef>` to make the `<royaleunit>` task available for use in our build file:
+
+```xml
+<taskdef resource="royaleUnitTasks.tasks" classpath="${royalesdk}/js/lib/royaleUnitTasks.jar"/>
+```
+
+Replace the `${royalesdk}` token with the path to the Apache Royale SDK on your computer.
+
+## Run unit tests in HTML and JavaScript
+
+To run unit tests with a web browser and JavaScript, set the `player` attribute to `"html"`. This tells the Ant task to use the WebSocket protocol. Set the `swf` attribute to the path to an *.html* file:
+
+```xml
+<royaleunit player="html" swf="${basedir}/bin/js-debug/index.html"/>
+```
+
+In the example above, we point to the *index.html* file generated by the Apache Royale compiler in *bin/js-debug*.
+
+By default, the unit tests will run in your computer's default web browser. To run in a specific web browser, you may specify the path to an executable using the `command` attribute.
+
+In the following example, we'll run unit tests in Google Chrome.
+
+On Windows, set the `command` to an *.exe* file:
+
+```xml
+<royaleunit player="html" swf="path/to/file.html"
+ command="c:/Program Files/Google/Chrome/Application/chrome.exe"/>
+```
+
+On macOS, set the `command` to the executable **inside** an *.app* package:
+
+```xml
+<royaleunit player="html" swf="${basedir}/bin/js-debug/index.html"
+ command="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"/>
+```
+
+## Run unit tests in Adobe Flash Player
+
+To run unit tests with Adobe Flash Player, set the `player` attribute to `"flash"`. Set the `swf` attribute to the path of a *.swf* file:
+
+```xml
+<royaleunit player="flash" swf="bin-debug/ExampleApp.swf"/>
+```
+
+The unit tests will run in your default application associated with *.swf* files. To run in a specific version of the standalone Adobe Flash Player projector, you may specify the path to the executable using the `command` attribute.
+
+On Windows, set the `command` to an *.exe* file:
+
+```xml
+<royaleunit player="flash" swf="bin-debug/ExampleApp.html"
+ command="path/to/flashplayer_32_sa_debug.exe"/>
+```
+
+On macOS, set the `command` to the executable **inside** an *.app* package:
+
+```xml
+<royaleunit player="flash" swf="bin-debug/ExampleApp.html"
+ command="/Applications/Flash Player.app/Contents/MacOS/Flash Player Debugger"/>
+```
+
+## Useful options
+
+To fail the Ant build if the unit tests fail, set the `haltonfailure` attribute to `true`:
+
+```xml
+<royaleunit player="html" swf="${basedir}/bin/js-debug/index.html" haltonfailure="true"/>
+```
\ No newline at end of file