django-qunit

django-qunit integrates the QUnit Javascript testing framework with Django, making it possible to run QUnit tests alongside your Django app and test Ajax routines.

Installation

1. Either:

• Install via pip install django_qunit2
• Download the files / clone the repo and put the django_qunit/django_qunit folder where ever you put your projects apps

1. Add django_qunit (or apps.django_qunit, depending on which option you chose for the first step) to your settings.INSTALLED_APPS.
2. Add 'django_qunit.snippet_loader.Loader', to settings.TEMPLATE_LOADERS.
3. Add settings.QUNIT_TEST_PATH, containing the path to the qunit test directory from within each app's static files directory, and your main project static directory. This is a file path, so make sure to use os.path.join to create the path.

For example, if STATICFILES_DIRS contains "/path/to/my/project/static" and QUNIT_TEST_PATH is "qunit", place your test files inside a "qunit" folder in os.path.join("/path/to/my/project/static", QUNIT_TEST_PATH). Within each app, you should put the files in appname/static_dir/QUNIT_TEST_PATH/appname/. Adding in appname keeps tests namespaced and creates a natural tree structure for your tests.

4. Add a urlconf to include('django_qunit.urls').

If you would only like these urls available in debug mode, use something like the following in your base urls.py file.

    if settings.DEBUG:
        """Test-only urls """
        urlpatterns += patterns('',
            (r'^qunit/', include('django_qunit.urls')),
        )  

5. Visit the URL you've included in your urlconf, and it should display QUnit test results.

Configuration

• Qunit test directory layout

  Extending upon the contents of the examples directory, we found something resembling the following works well, assuming qunit is your QUNIT_TEST_PATH. Group tests into files then folders. Folders can be nested.

    * qunit
        * section_a
            * test1.js
            * test2.js
            * stub_a.html
            * suite.json
        * section_b
            * section_b1
                * test1.js
            * test1.js
            * suite.json
        * section_c
            * test1.js
        * test1.js
        * suite.json
  

  Within an app, first create a empty folder with the name of the app, then add more tests and test directories with that.

    * qunit
        * myapp
            * test1.js
            * test2.js
            * stub1.html
            * suite.json
            * section_a
                * section_b1
                    * test1.js
                * test3.js
                * suite.json
            * section_b
                * test4.js
  

• Test configuration files

  Add a file named suite.json to any directory in QUNIT_TEST_DIRECTORY to change the displayed name of that testing directory or change what external assets are loaded on that test page. For example, the following will load the js files at the listed urls into the page django-qunit creates for the folder containing this configuration file.

  You can also pass an array named extra_media_urls, and these urls will be concatenated with your project's value of settings.MEDIA_URL.

    {
        "extra_urls": [
          "/static_assets/js/lib/jquery.js",
          "/static_assets/js/lib/underscore.js",
          "/static_assets/js/lib/jquery-ui.js"
        ]
    }
  

  Note that suite.json attributes are not inherited by lower level directories, so you need to define suite.json files for each folder that needs additional assets loaded.

  Additionally, you can include .html files in any testing directory. The contents of each of these files will be included on that directory's testing page inside a div with an id determined by the name of the file. For example, for the example stuctur above, stub_a.html would be included in a div with id stub_a. All html stubs are wrapped in a div with id qunit-html-stubs, and this div is given the css property display: none.

Tips

• You must have "django.contrib.staticfiles.finders.AppDirectoriesFinder" listed as one of your "STATICFILES_FINDERS"
• Your Django installation should be looking for static files under "appname/static". If you changed this, the static files for qunit may not be found.

License

Copyright (c) 2012 Timothy Van Heest

Originally based off a fork of Cody Soyland's django-qunit.

Licensed MIT, also containing QUnit, which is licensed MIT. See LICENSE file for more information.