Commits

Kumar McMillan committed 6cdbda0

bumped version, cheangelog, and updated docs for lint features

  • Participants
  • Parent commits 6dac0f7

Comments (0)

Files changed (3)

 
-NoseJS is a `Nose`_ plugin to run JavaScript tests using `Rhino`_ in a Java subprocess.
+NoseJS is a `Nose`_ plugin to integrate JavaScript tests into a Python test suite.
 
 .. _Nose: http://www.somethingaboutorange.com/mrl/projects/nose/
 .. _Rhino: http://www.mozilla.org/rhino/
 
 .. contents::
 
+Overview
+========
+
+NoseJS is designed for Python projects that require JavaScript code for some Web functionality.  It currently has two features:
+
+- Discover and run JavaScript tests alongside Python tests
+- Validate JavaScript syntax (check for lint).
+
 Install
 =======
 
-First, you need to download `Rhino`_.  More on that below.
+There are some optional external dependencies in the sections below.
 
 You can get NoseJS with `easy_install <http://peak.telecommunity.com/DevCenter/EasyInstall>`_ ::
     
     
     $ python setup.py develop
 
+Checking JavaScript Syntax
+==========================
+
+NoseJS will find JavaScript files (e.g. ``app.js``) along the Nose path and run them through the `jsl`_ command line tool to check for "lint."  In other words, show you syntax errors, warnings, etc.  You can install jsl on most systems using your package manager (i.e. ``port install javascript-lint`` on Mac OS X) otherwise it is available for download on the `jsl`_ site.  
+
+.. _jsl: http://www.javascriptlint.com/
+
 Usage
-=====
+-----
 
-Here is the most basic way to invoke NoseJS (assumes you've downloaded `Rhino`_ into ~/src) ::
+To check for lint without running any JavaScript unit tests, type::
     
-    $ nosetests --with-javascript --rhino-jar ~/src/rhino1_7R1/js.jar 
+    $ nosetests --with-javascript --no-javascript-tests path/to/javascript
+
+To disable lint checking, add ``--no-javascript-lint``
+
+Running JavaScript Tests
+========================
+
+NoseJS will also find and run JavaScript test files, those that match Nose's test pattern and end in ``.js``.  Currently, NoseJS supports running executing tests in `Rhino`_, a Java implementation of the JavaScript language.  There is experimental support for `python-spidermonkey <http://github.com/davisp/python-spidermonkey/tree/master>`_ using the ``--spidermonkey`` switch.
+
+Usage
+-----
+
+Assuming you've downloaded `Rhino`_ into ``~/src``, discover and run JavaScript tests with this command::
+    
+    $ nosetests --with-javascript --rhino-jar ~/src/rhino1_7R1/js.jar path/to/javascript/tests
 
 This command would look for any files along Nose's path ending in .js that match Nose's current test pattern, collect them all, then execute them using Rhino in a single Java subprocess at the end of all other tests.  By default, files looking like ``test*.js`` will be collected and run.
 
 The dots are the Python tests that were run and the output below that is what Fudge's JavaScript test files printed out.  Be sure to read the Caveats section below ;)
 
 Specifying a path to JavaScript files
-=====================================
+-------------------------------------
 
 If JavaScript files are nested in a subdirectory, like the above example, specify that directory with::
     
     $ nosetests --with-javascript --js-test-dir javascript/fudge/tests/ --js-test-dir ./another/dir
 
 nosejs JavaScript namespace
-===========================
+---------------------------
 
 All JavaScripts have the ``nosejs`` JavaScript namespace available for use.  The following methods are available:
 
         }
 
 Using the DOM
-=============
+-------------
 
 If your JavaScript under test relies on a browser-like DOM environment, it might still work!  Just run::
     
 This will load a copy of John Resig's `env.js <http://ejohn.org/projects/bringing-the-browser-to-the-server/>`_ script to simulate a DOM before loading any other JavaScript.  There are a few very minor patches made to env.js, marked with @@nosejs in the NoseJS source.
 
 Caveats
-=======
+-------
 
 - Currently if JavaScript tests fail, nosetests **will not** indicate failure and its exit status will be unaffected.  I can't figure out a clean way to do this.  Please get in touch if you'd like to help.  
 - In general, JavaScript tests are not very well integrated into Nose.
 
 Wait ... Python *and* Java?
-===========================
+---------------------------
 
 `Rhino`_ is pretty much the only stable, command line oriented implementation of JavaScript I know of and it's well supported by Mozilla.  
 
-Alternatively, John J. Lee created a Python binding to the fast `Spider Monkey engine <http://www.mozilla.org/js/spidermonkey/>`_, Atul Varma revived it once in a fork on `Google Code <http://code.google.com/p/python-spidermonkey/>`_, and now Paul J. Davis is working on it (in `git <http://github.com/davisp/python-spidermonkey/tree/master>`_ and it is released on `PyPI <http://pypi.python.org/pypi/python-spidermonkey>`_).  I have only had success in building Atul's fork and unfortunately the error messages leave a lot to be desired.  However, I have a basic implementation of NoseJS that supports a ``--spidermonkey`` option, which switches out the JavaScript engine.  The code is here in a fork: http://bitbucket.org/kumar303/nosejs-spidermonkey/.
+Alternatively, John J. Lee created a Python binding to the fast `Spider Monkey engine <http://www.mozilla.org/js/spidermonkey/>`_, Atul Varma revived it once in a fork on `Google Code <http://code.google.com/p/python-spidermonkey/>`_, and now Paul J. Davis is working on it (in `git <http://github.com/davisp/python-spidermonkey/tree/master>`_ and it is released on `PyPI <http://pypi.python.org/pypi/python-spidermonkey>`_).  
 
-Once Python Spidermonkey becomes a bit more stable it would be nicer than Rhino because tests could be executed inline alongside other Python tests without the overhead of starting up a Java process.  
+There is current experimental support for Python Spidermonkey in NoseJS using the ``--spidermonkey`` option, which switches out the JavaScript engine.
 
 Contributing
 ============
 - 0.9
   
   - Initial release
-  
+
+To Do
+=====
+
+- Better spidermonkey support
+- Distribute a Rhino js.jar with NoseJS
+- Upgrade env.js using git repo
 
     def configure(self, options, config):
         Plugin.configure(self, options, config)
+        if not self.enabled:
+            return
+            
         self.files = [] # used by self.wantFile()
+        self.javascript_test_dirs = set([])
         
         if options.run_javascript_tests:
             self._configureJsTesters(options, config)
         #   /path/to/somewhere/
         #   /path/to/somewhere/else/
         
-        self.javascript_test_dirs = set([])
         root = os.getcwd()
         for dir in options.javascript_test_dirs:
             absdir = os.path.abspath(dir)
 setup(
     name='NoseJS',
     version=version,
-    description="A Nose plugin to run JavaScript tests using Rhino in a Java subprocess.",
+    description="A Nose plugin to integrate JavaScript tests into a Python test suite.",
     long_description=open("README.txt",'r').read(),
     zip_safe=False,
     packages=find_packages(),