refs #728 - added notes about preconfigured casper test instance overriding

@@ -99,6 +99,7 @@ The `casperjs` command has three available options:
 .. warning::
 .. warning::
 
 
    .. deprecated:: 1.1
    .. deprecated:: 1.1
+
    ``--direct`` option has been renamed to ``--verbose``, though ``--direct`` will still works, while is to be considered deprecated.
    ``--direct`` option has been renamed to ``--verbose``, though ``--direct`` will still works, while is to be considered deprecated.
 
 
 Example:
 Example:

@@ -330,6 +330,17 @@ Of course, it's a whole lot more verbose, but Casper provides convenient methods
         this.echo('Element HTML is now: ' + this.getElementInfo('h1').html);
         this.echo('Element HTML is now: ' + this.getElementInfo('h1').html);
     });
     });
 
 
+.. _faq_test_casper_instance:
+
+Why can't I create a new `casper` instance in a test environment?
+-----------------------------------------------------------------
+
+The `casperjs test` :ref:`subcommand <test_subcomand>` is a convenient utility which bootstraps and configures a :ref:`test environment <testing>` for you, so a preconfigured `casper` object is already available in your test script when using this command.
+
+As of 1.1-beta3, you're prevented to override this preconfigured instance at this practice prevents the test runner to work properly. If you try to create a new casper instance in a test script, you'll get an error and CasperJS will exit with an error message with a link pointing to the documentation.
+
+One may argue this is mostly related to some hostorical bad design decision, and she might be true. This behavior is not likely exist anymore in a future 2.0.
+
 .. _faq_javascript:
 .. _faq_javascript:
 
 
 Okay, honestly, I'm stuck with Javascript.
 Okay, honestly, I'm stuck with Javascript.

@@ -12,9 +12,10 @@ CasperJS ships with its own :doc:`testing framework <modules/tester>`, providing
 
 
     .. versionchanged:: 1.1
     .. versionchanged:: 1.1
 
 
-    The testing framework — hence its whole API — can only be used when using the ``casperjs test`` subcommand.
+    The testing framework — hence its whole API — can only be used when using the ``casperjs test`` subcommand:
 
 
-    If you try to use the ``casper.test`` property out of the testing environment, you'll get an error.
+    - If you try to use the ``casper.test`` property out of the testing environment, you'll get an error;
+    - As of 1.1-beta3, you can't override the preconfigured ``casper`` instance in this test environment. You can read more about the whys in the :ref:`dedicated FAQ entry <faq_test_casper_instance>`.
 
 
 .. index:: Unit testing
 .. index:: Unit testing
 
 
@@ -135,6 +136,7 @@ The :ref:`Tester#begin() <tester_begin>` accepts either a function or an object
         }
         }
     });
     });
 
 
+.. _test_subcomand:
 
 
 Test command args and options
 Test command args and options
 -----------------------------
 -----------------------------