Permalink
Browse files

Adding the testing guides

  • Loading branch information...
oldfartdeveloper authored and wagenet committed Feb 13, 2011
1 parent a68e3e9 commit 7926b4dd8a9e5a8ba872cdbf6ef8f4541466d086
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
View
@@ -73,3 +73,25 @@ index:
url: chance
text: "Chance is SproutCore's CSS preprocessor. In this guide, you will learn how to use the CSS extensions that come with Chance to streamline your styling workflow."
construction: true
+ Testing:
+ - title: "Unit Testing"
+ url: unit_test_framework
+ text: "SproutCore has an easy-to-learn unit test facility that can be used to drive SproutCore test-driven development. This guide describes the basic SproutCore test commands."
+ - title: "Adding a Unit Test"
+ url: adding_unit_test
+ text: "Adding a unit test automatically or manually."
+ - title: "Writing Unit Tests"
+ url: writing_unit_tests
+ text: "Describes how to write unit tests using +modules+ and +tests+"
+ - title: "Running Unit Tests"
+ url: running_unit_tests
+ text: "How tests are loaded and executed by the test runner."
+ - title: "Testing Guidelines in SproutCore"
+ url: testing_guidelines
+ text: "Developing a SproutCore application using test-driven development (TDD)."
+ construction: true
+ - title: "SproutCore Development Using TDD"
+ url: todos_tdd
+ text: "Show implementing the TODOs project using TDD."
+ construction: true
+
@@ -0,0 +1,166 @@
+h2. Unit Testing - Adding Unit Test Files
+
+This guide covers unit test file generation and organization. After reading this guide, you will be able to:
+
+* Automatically generate a unit test file that will be placed in the correct location.
+* Manually create a unit test file from a template.
+* Manually create unit test files.
+* Arrange your unit test files.
+
+endprologue.
+
+
+h3. Creating a Directory for your Unit Test Files
+
+When you first create your Sproutcore application, directories are automatically created for you.
+
+<plain>
+$ sc-init MyApp
+ ~ Created directory at my_app
+ ~ Created file at my_app/Buildfile
+ ~ Created file at my_app/README
+ ~ Created directory at apps
+ ~ Created directory at apps/my_app
+ ~ Created directory at apps/my_app/resources
+ ~ Created file at apps/my_app/resources/main_page.js
+ ~ Created file at apps/my_app/resources/loading.rhtml
+ ~ Created file at apps/my_app/core.js
+ ~ Created file at apps/my_app/main.js
+Your new SproutCore project is ready!
+</plain>
+
+By convention, SproutCore assumes that all unit tests files are located in the +tests+ sub-directory for your application (or framework).
+
+@my_app/apps/my_app/tests@
+
+Hence, create the +tests+ directory if it is missing.
+
+Unlike like most folders, SproutCore assumes that each file in the tests
+directory that ends in '.js' or '.rhtml' is a unit test. You can load each
+of these unit tests individually or as a group from the built-in test runner.
+
+NOTE: The files in the +tests+ directory are omitted from your production deployment.
+
+h3. Creating a Unit Test File
+
+SproutCore unit test cases are coded and saved into unit test files under the +tests+ directory.
+
+It is good practice to group related unit test cases into a single unit test file. For example, all test cases for a +login+ controller class should be saved in a unit test file called +login.js+.
+This is way, when a change is made to the login controller class, we can run all the unit test cases in +login.js+ to verify.
+
+In addition, it is good practice to group related unit test files into a sub-directory under the +tests+ directory. For example, unit test files for controllers should be saved in the +tests/controller+ directory. In this way, if a change is made to all controllers, we run the unit test cases in all unit test files in the +controller+ directory to verify.
+
+There are three ways to create your unit test files.
+
+h4. Automatically Creating Unit Test Files
+
+When you use the +sc-gen+ tool to add new source files to your application, it will automatically add a corresponding test file added into the +tests+ directory. For example,
+
+<plain>
+$ sc-gen controller MyApp.LoginController
+ ~ Created directory at controllers
+ ~ Created file at controllers/login.js
+ ~ Created directory at tests
+ ~ Created directory at tests/controllers
+ ~ Created file at tests/controllers/login.js // <== The generated unit test file
+
+Your controller is now ready to use!
+</plain>
+
+Notice the creation of +tests/controllers/login.js+.
+
+Conveniently, the generated unit test file is built from a template:
+
+<javascript>
+// ==================================================
+// Project: MyApp.loginController Unit Test
+// Copyright: ©2011 My Company, Inc.
+// ==================================================
+/*globals MyApp module test ok equals same stop start */
+
+module("MyApp.loginController");
+
+// TODO: Replace with real unit test for MyApp.loginController
+test("test description", function() {
+ var expected = "test";
+ var result = "test";
+ equals(result, expected, "test should equal test");
+});
+</javascript>
+
+h4. Generating Unit Test Files
+
+You can also use the +sc-gen+ tool to create your unit test file by itself:
+
+<plain>
+$ sc-gen test TARGET_NAME PATH/TO/TEST[.js]
+</plain>
+
+For example, if you wanted to add a unit test file named +views/login/render.js+ to your application, you would:
+
+<plain>
+$ sc-gen test MyApp views/login/render
+ ~ Created file at tests/views/login/render.js
+
+Your unit test has been generated and is now ready to be configured!
+</plain>
+
++render.js+ contains a sample unit test case to help you get started.
+
+<plain>
+// ==================================================
+// Project: MyApp Unit Test
+// Copyright: ©2011 My Company, Inc.
+// ==================================================
+/*globals MyApp module test ok equals same stop start */
+
+module("MyApp");
+
+// TODO: Replace with real unit test
+test("test description", function() {
+ var expected = "test";
+ var result = "test";
+ equals(result, expected, "test should equal test");
+});
+</plain>
+
+
+
+h4. Manually Creating Unit Test Files
+
+If you cannot or would prefer not to use the +sc-gen+ tool, you can always add a unit test manually.
+
+Just create a new +.js+ file in your +tests+ directory. It will be automatically run by the test runner when appropriate.
+
+h3. How to Arrange Your Unit Tests
+
+The SproutCore Test Runner can run:
+
+_TODO: needs elaboration. The problem is that we haven't expanded on the concept that the test runner can run all tests on all applications (or a subset of them)._
+
+* an individual unit test file,
+* all unit test files a directory, or
+* all unit test files for a particular target (i.e. application or framework).
+
+Unit tests work best if you arrange them into files and directories based on how you might want to run them together. Often, it is a good practice is to create a directory for each class you add
+to your app and one unit test file per method you want to test inside that directory.
+For example, the unit tests for SC.Object might look something like:
+
+<plain>
+tests/system/object/create.js
+tests/system/object/extend.js
+tests/system/object/kindOf.js
+...
+</plain>
+
+This way you can easily run all of the unit tests for a particular method,
+all of the unit tests for the SC.Object class itself or all of the unit tests
+for classes defined in the "system" directory of the target.
+
+
+h3. Moving On
+
+Once you've added a unit test file, now you need to write some unit test code.
+Learn more by writing your first unit test.
+
+On to "Writing Unit Test Cases »":/writing_unit_tests.html
@@ -0,0 +1,98 @@
+h2. UnitTesting - Running Unit Tests
+
+ After reading this guide, you will be able to:
+
+* Understand how unit test files are loaded and executed
+* Use the GUI Test Runner
+* Manually run unit test(s)
+
+endprologue.
+
+
+h3. How Unit Test Cases Are Loaded and Executed
+
+When you run a unit test, SproutCore retrieves and runs the source unit test JavaScript and renders the results as an HTML page.
+
+SproutCore does this in the following sequence:
+
+# Load the application including its dependencies.
+# Load the unit tests.
+# Instead of calling the main application's +main()+ function, runs all or some of the unit tests.
+# Like most javascript test frameworks, SproutCore renders the results in a nicely-formatted HTML page.
+
+The advantage is that your unit tests are run in an environment that is very close to the actual combination of code and resources that will be available to your application when it runs.
+
+It also means that if you write code that runs on page load BEFORE the +main()+ method is called, it could be executed even in test mode. Make sure that any code you write to run at early page startup can deal with being loaded in test mode as well.
+
+
+
+
+h3. Using the SproutCore Test Runner
+
+NOTE: The new Abbot tools do not yet support the test runner. Until they do, you should follow the "Running Tests Manually" section below.
+
+h4. Starting the Test Runner
+
+The easiest way to run unit tests is to simply visit the built-in unit test runner by starting your browser and navigating to +http://localhost:4020+, then selecting +tests+ from the application list as shown.
+
+!images/testing/unit_test_2.jpg(Test Runner)!
+
+For quicker access, bookmark "http://localhost:4020/sproutcore/tests":http://localhost:4020/sproutcore/tests.
+
+
+h4. Selecting and Running Tests
+
+Suppose your application is named "my_app". To see a list of your unit tests, in the left hand column under +APPS+, double-click "my_app":
+
+!images/testing/unit_test_3.png(Test Runner Unit Test Files)!
+
+Run all the unit test cases within a file by clicking on it.
+
+
+NOTE: The "+Using Continuous Integration+" checkbox and the "+Run Tests+" button are under construction.
+
+
+h3. Running Selected Unit Tests
+
+NOTE: The instructions in this section only apply to SproutCore revision level 1.5 and above.
+
+h4. Running An Individual Unit Test File
+
+Sometimes you may want to run unit tests manually outside of the test runner. For example, perhaps you have a continuous integration environment and would like to use Selenium to evaluate the results of running your unit tests.
+
+All unit tests for an application or framework can be found at an easily computed URL using the following format:
+
+@http://localhost:4020/sproutcore/tests#APP_NAME&test=PARTIAL_PATH_TO_APP@
+
+where:
+
+* APP_NAME is your application name.
+* PARTIAL_PATH_TO_APP is the subpath from the +PROJECT_FOLDER/apps/APP_NAME/tests+ folder. It should include the body of the javascript file name but not the +.js+ extension.
+
+As an example, suppose you have a unit test file located at:
+
+@PROJECT_HOME/apps/my_app/tests/unit/sample.js@
+
+To run this test, browse:
+
+@http://localhost:4020/sproutcore/tests#my_app&test=unit/sample@
+
+h4. Loading All Unit Tests In a Directory
+
+NOTE: Under Construction
+
+h4. Loading All Unit Tests in a Target
+
+NOTE: Under Construction
+
+h4. Loading Tests from Nested Targets
+
+NOTE: Under Construction
+
+h3. Moving On
+
+This concludes the main programming guide for working with Unit Tests in SproutCore applications. You're now ready to change the world with awesome unit tests!
+
+On to the "SproutCore Testing Guidelines »":/testing_guidelines.html
+
+
@@ -0,0 +1,20 @@
+h2. SproutCore - Testing Guidelines
+
+This guide covers using test-driven development (TDD) techniques to develop SproutCore applications.
+After reading this guide, you will be able to:
+
+* Write tests for methods to be implemented and use them to help you implement them.
+* Write tests to verify that your observers fire when you expect them to.
+* Write tests that verify your bindings fire when you expect them to and how to
+incorporate +SC.RunLoop+ so that they will function.
+* _TODO_: more
+
+endprologue.
+
+WARNING: This guide is under construction.
+
+h3. Test-drive SproutCore Method Implementation
+
+h3. Test-drive Observer Implementation
+
+h3. Test-drive Bindings Implementation
@@ -0,0 +1,26 @@
+h2. SproutCore - Testing Guidelines
+
+This guide covers using test-driven development (TDD) techniques to develop SproutCore applications.
+After reading this guide, you will be able to:
+
+* Write tests for methods to be implemented and use them to help you implement them.
+* Write tests to verify that your observers fire when you expect them to.
+* Write tests that verify your bindings fire when you expect them to and how to
+incorporate +SC.RunLoop+ so that they will function.
+* _TODO_: more
+
+endprologue.
+
+WARNING: This guide is under construction.
+
+h3. Test-drive SproutCore Method Implementation
+
+h3. Test-drive Observer Implementation
+
+h3. Test-drive Bindings Implementation
+
+h3. Next
+
+Let's reinvent the *todos* project using TDD techniques.
+
+On to "SproutCore Development Using TDD »":/todos_tdd.html
Oops, something went wrong.

0 comments on commit 7926b4d

Please sign in to comment.