Installation¶

1. Download the KA Lite OSX installer.
2. After the download is complete, double click the .dmg file.
3. Click the Agree button to accept the LICENSE agreement.
4. On the .dmg window, drag the KA-Lite Monitor app into the Applications folder.
5. Launch KA-Lite Monitor from your Applications folder.
6. On first load, it will check your current environment and show the Preferences dialog.
7. Input your preferred administrator username and password, then click the Apply button in KA-Lite Preferences dialog.
8. You will be prompted that initial setup will take a few minutes, click the OK button and wait for the notification that KA-Lite has been setup and can now be started.
9. Click on the KA-Lite logo icon on the menu bar and select the Start KA-Lite menu option.
10. Wait for the notification that you can now click on Open in Browser menu option.
11. Click on the KA-Lite logo icon on the menu bar and select Open in Browser menu option - this should launch KA-Lite in your preferred web browser.
12. Login using the administrator account you have specified during setup.

Upgrade¶

To upgrade an existing KA Lite installation.

1. Download the KA Lite OSX installer.
2. After the download is complete, double click the .dmg file.
3. Click the Agree button to accept the LICENSE agreement.
4. On the .dmg window, drag the KA-Lite Monitor app into the Applications folder.
5. Give confirmation to overwrite the existing app.
6. Launch KA-Lite Monitor from your Applications folder.

Main method: Ubuntu/Debian .deb¶

Download the latest .deb manually from our server. After that, you can install the .deb file like this:

sudo dpkg -i FILENAME.deb

FILENAME should be replaced with the name of the file you downloaded. The file may be named as if it was intended for Ubuntu but works just as well for any other Debian-based systems like Debian, Raspberry Pi, Linux Mint etc.

You will be prompted to enter some configuration information. You should read the on-screen instructions carefully, but some explanation is included here:

1. You will be asked to choose to run KA Lite on boot or not. We recommend choosing yes, as it simplifies data management. If you choose no, you must manually start KA lite every time. Note that running KA Lite as different users creates different sets of data files, so it’s recommended that you run KA Lite as the same user every time.

2. If you chose to start on boot in the previous step, you will be prompted to choose the owner for the KA Lite server process. Generally the default value is ok.

3. You will be asked to review your choices, and finally KA Lite will start automatically when installation is complete.

Raspberry Pi¶

For a Raspberry Pi running a Debian system, you can install the special Debian package ka-lite-raspberry-pi.

It can be installed by downloading the latest .deb on the Pi and installing it:

# Install dependencies
sudo apt-get install python-m2crypto python-pkg-resources nginx python-psutil
# Fetch the latest .deb
sudo wget https://learningequality.org/r/deb-pi-installer-0-15 --no-check-certificate --content-disposition
# Install the .deb
sudo dpkg -i ka-lite-raspberry-pi*.deb

You can also add the PPA, see Debian/Ubuntu: Subscribe to updates through a PPA, and then run sudo apt-get install ka-lite-raspberry-pi.

After installing, you can setup a Wifi hotspot using this guide: Raspberry Pi Wi-Fi

Other options¶

KA Lite is available for all platforms (e.g. non-Debian compatible platforms) through PyPi. See Generic installation (pip install).

Configuration after installation or update¶

Every time you install or update KA Lite, you must run kalite manage setup command again to setup the database and download assessment items (video descriptions, exercises etc.).

Windows¶

1. Uninstall KA Lite from the Control Panel.
2. In Windows XP, double-click the “Add or Remove Programs” icon, then choose KA Lite.
3. In later version of Windows, click the “Programs and Features” icon, then choose KA Lite.

Mac OSX¶

1. Launch KA-Lite Monitor from your Applications folder.
2. Click on the app icon at the menu bar.
3. Click on Preferences in the menu option.
4. Click the Reset App from the Advanced tab.
5. You will be prompted that “This will reset app. Are you sure?”, just click on OK button.
6. Another dialog will appear asking your Password, type your password then click on Ok button.
7. Quit the KA-Lite Monitor app (do not click the Apply button!).
8. Move the KA-Lite Monitor app to Trash.

Linux: Debian/Ubuntu¶

Option 1: Open up Ubuntu Software Center and locate the KA Lite package. Press Remove.

Option 2: Use apt-get remove <name of package>. You have to know which package you installed, typically this is ka-lite or ka-lite-bundle.

Installed with pip¶

You can remove KA Lite (when installed from pip or source distribution) with pip uninstall ka-lite or pip uninstall ka-lite-static (static version).

Removing user data¶

Some data (like videos and language packs) are downloaded into a location that depends on the user running the KA Lite server. Removing that directory can potentially reclaim lots of hard drive space.

On Windows, the HOME and USERPROFILE registry values will be used if set, otherwise the combination %HOMEDRIVE%%HOMEPATH% will be used. You can check these values from the command prompt using the commands echo %HOME%, echo $USERPROFILE%, etc. Within that directory, the data is stored in the .kalite subdirectory. On most versions of Windows, this is C:\Users\YourUsername\.kalite\.

On Linux, OSX, and other Unix-like systems, downloaded videos and database files are in ~/.kalite.

0.15.0¶

0.14.0¶

kalite manage setup --git-migrate=/path/to/your/old/installation/ka-lite

0.13.0¶

bin/kalite manage setup

bin\windows\kalite.bat manage setup

Debian/Ubuntu: Subscribe to updates through a PPA¶

We maintain a PPA on Launchpad and if you are connected to the internet, this will also give you automatic updates:

sudo apt-get install software-properties-common python-software-properties
sudo add-apt-repository ppa:learningequality/ka-lite
sudo apt-get update
sudo apt-get install ka-lite

User interface for Debian/Ubuntu¶

Make sure you have the PPA added, then run:

sudo apt-get install ka-lite-gtk

Development¶

A guide recommending how to install KA Lite for development is available in Setting up your development environment.

Generic installation (pip install)¶

$> pip install ka-lite

$> pip install ka-lite-static

$> sudo python setup.py install.

Specific system setups¶

<VirtualHost *:80>
    ServerName kalite.com
    DocumentRoot /var/www/html/

    Alias /static /var/www/.kalite/static
    Alias /media /var/www/.kalite/media

    WSGIScriptAlias / /usr/lib/python2.7/dist-packages/kalite/project/wsgi.py

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    ErrorLog ${APACHE_LOG_DIR}/kalite-error.log
    CustomLog ${APACHE_LOG_DIR}/kalite-access.log combined
</VirtualHost>

module = kalite.project.wsgi

$> sudo su -s /bin/bash www-data
$> kalite manage setup
$> exit

Supported Browsers¶

KA Lite is currently not supported on Internet Explorer version 8 or lower. You must use IE9 or later. You can also use KA Lite on browsers like Firefox, Chrome, and Safari! There are no known issues with current versions of these browsers.

Administrator Glossary¶

If you choose to register online, these important terms will help you better understand the flow of data between your installations and the online data hub.

Sharing Network

A Sharing Network is a group of devices that share user data. This data is synced to the central server when an Internet connection is available, and then synced down onto other devices in the same Sharing Network.

Organization

An organization is a group of people responsible for administering a set of Sharing Networks. An organization can have multiple administrators and manage multiple sharing networks.

Facility

A facility is the physical space in which a device is located (e.g. a school or a computer lab in a community center). Learner, coach, and admin accounts are associated with a particular facility.

Device

A device should be able to run a KA Lite server (most computers) and other devices to be used as clients. One common configuration is using a Raspberry Pi or other inexpensive computer as a server and relatively cheap tablets as client devices. Tablets can access the servers through an access point, such as a Wi-Fi dongle, or some other networking device such as a router.

Web Browser

A program that retrieves and presents information resources on the World Wide Web. Popular web browsers include Internet Explorer, Google Chrome, Mozilla Firefox, and Safari.

Running the KA Lite Server¶

At the very end of the setup, you have been prompted to run kalite. Make note of the command to run the server, which was also mentioned. Usually it’s just kalite start.

Windows or OSX behind a Firewall¶

During the process, your operating system might prompt you to allow “Python.app” to accept incoming connections. The message dialogue may look like the following, depending on your operating system:

Please allow the app to run. This will make it possible for the KA Lite application to be accessible.

Accessing KA Lite¶

Once the server has been started, you will be given a few IP addresses. You can use these addresses to access KA Lite by copying and pasting them into a web browser of your choice.

In order to access KA Lite from another machine, please enter the IP address that does not start with http://127.0.0.1:8008 into the web browser on that machine.

Setting up KA Lite¶

Once you have successfully installed KA Lite, the installation script should give you a URL (http://127.0.0.1:8008/) to visit so that you can open KA Lite and login for the first time.

Copy and paste the URL into a web browser. The KA Lite application should show up. Then, login to KA Lite using the username and password you created during the installation process.

• If you have forgotten the username/password combination, simply run kalite manage createsuperuser and then follow the instructions.

Once you’ve logged in, the next step in the setup process is registering your device with the KA Lite Hub.

How to register your device with online access to data¶

Note

You will need Internet access in order to perform these steps.

1. Log into KA Lite with the username and password that you set during set-up.
2. If you have not already registered your device, you will be redirected to a page that shows you your options. Click the “Register with an online account now!” button to get started with the registration process.

If you do not see this page, click on the “Manage” tab. At the top of this page, you should see a link to register your device. It should like like the following:

You will be prompted to log in with your central server login credentials. Please note that these credentials are different from your login credentials created during set-up. Click on the “Sign up here” link, and you will be redirected to a page that prompts you to create an account on the central server.

Once you have filled out the form and submitted it, you will be sent an activation link via the email address you supplied.

Post Registration Setup¶

Now that you have registered successfully, it’s time to configure your local KA Lite installation to suit your needs. If any terms like ‘facility’ or ‘device’ become confusing, feel free to reference the Administrator Glossary for a quick reminder.

Create a Facility¶

KA Lite assumes that you are going to be using the software primarily in one place. This could be a school, a home, a community center, etc. We call this place a “facility”, and use it to help differentiate users who are syncing back data with our central data hub. In order to create a facility, follow the steps below.

1. Log in to KA Lite.
2. Click the “Manage” tab at the top of the page.

3. Make sure that the “Facilities” tab is selected.
4. Under the Facilities section, click on “Add a new facility...”

5. Fill in the information for all the fields you find below the map
6. Click the “Save facility” button when you are finished.

7. Once the information has been saved, you will be redirected back to the “Facilities” page, where you will see a message indicating that you have successfully saved your new facility.

Delete a Facility¶

1. Log in to KA Lite.
2. Click the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.

4. Find the facility you would like to delete, and click the trash can icon to delete the facility.

5. You will be prompted to type in the name of the facility you wish to delete for confirmation.
6. If your delete is successful, you will be redirected back to the “Facilities” page, where you will see a message indicating that you have successfully deleted the facility.

User Management¶

Coaches and learners are the other types of users that KA Lite supports. In order for them to be able to login, you need to create accounts for them.

Adding Learners¶

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the learner will belong to.

5. Under the “Learners” header, click on “Add a new Learner”.

6. You will be redirected to a page that says “Add a new Learner”. Fill in all the information. The facility dropdown defaults to the facility you selected in the previous steps.
7. Click “Create user”. You should be redirected to the “Facilities” page, where you will see a message indicating that you have successfully created a Learner user.

Permanently Deleting Learners¶

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Under the “Facilities” header, select the facility the Learner belongs to.
5. Under the “Learners” header, mark the box to the left of the Learner account you would like to delete.

6. Press the “Delete Learners” button.

7. You will be prompted with a confirmation of your deletion. Press “OK” to proceed with the deletion.

Adding Coaches¶

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the coach will belong to.
5. Under the “Coaches” header, click on “Add a new coach”.

6. You will be redirected to a page that says “Add a new coach”. Fill in all the information. The facility dropdown defaults to the facility you selected in the previous steps.
7. Click the “Create User” button.

8. If the user was successfully created, the page will reload with a message indicating that you have created the user.

Permanently Deleting Coaches¶

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Under the “Facilities” header, select the facility the coach belongs to.
5. Under the “Coaches” header, mark the box to the left of the coach account you would like to delete.

6. Press the “Delete Coaches” button.

7. You will be prompted with a confirmation of your deletion. Press “OK” to proceed with the deletion.

Adding a Group¶

You can create groups within a facility. Each group can represent a classroom, a study group, or any other way you would like to group Learners. To create a group, follow the instructions below:

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the group will belong to.
5. Under the “Learner Groups” header, click on “Add a new group”.

6. Fill out the name of the group, and provide a description.
7. Click “create group”.

8. You should be redirected back to the page for the facility. If the group was successfully created, you will see it listed under the “Learner Groups” section.

Deleting a Group¶

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the group you would like to delete belongs to.
5. Mark the box to the left of the group you would like to delete.
6. Press the “Delete Groups” button under the “Learner Groups” header.

7. You will be prompted with a confirmation of your deletion. Press “OK” to proceed with the deletion.

Moving a User to a New Group¶

1. Navigate to the page for the facility the user belongs to.
2. Under the “Learners” header, select the Learner you would like to move by clicking in the checkbox to the left of the Learner name.

3. In the dropbox, select the group you would like to move the user to.

4. Click the “Change Learner Groups” button.

5. The page will refresh, with a message at the top indicating a successful move.

Group Summary Statistics¶

For each group, you should be able to view some statistics.

1. Navigate to the Learner Groups section of the facility you wish to look at.
2. Click on the group that you wish to view.

3. The statistics for the group should be displayed at the top of the page.

Allowing Other Users to Connect¶

In order for other users to be able to connect to the KA Lite server with a different machine, you will need to give them an IP address with which to access the software. This should be different from the IP address given to you during setup (127.0.0.1:8008).

Downloading Videos¶

Now that you’ve created a facility and user accounts, it’s time to add video content to your local KA Lite installation! Since the videos can take up a large amount of space, you can choose to download only the videos that you need. If your device has enough space and you wish to download all of the videos, we recommend skipping to Downloading Videos in Bulk .

Downloading Individual Videos¶

After registering your device:

1. Click the “Manage” tab at the top of the page.
2. Click on the “Videos” tab.

3. View subtopics by clicking on the ‘+’ symbol to the left of a subject of your choice. You can close them by clicking on the ‘-‘ symbol.
4. Mark the content you wish to download by clicking the checkbox to the left of the content name.
5. Click the green “Download” button in the top left box of the page. The button should also show you the total number of videos you have selected to download, as well as the total size of the content.
6. Once the download is completed, video content will be ready for Learners to watch!

Language Packs¶

KA Lite supports internationalization. You can download language packs for your language if it is available. A language pack comes with all the available subtitles and user interface translations for that language. When it is installed, KA Lite will give you the option to download individual dubbed videos from the language’s Khan Academy YouTube channel.

Download Language Packs¶

To download language packs:

1. From the “Manage” page, click on the “Language” tab.

2. Select the language pack you wish to download by selecting from the drop-down menu.

3. Click the “Get Language Pack” button.

4. Once the download finishes, you can see your language pack in the list of installed packs, but you MUST restart your server to make them available for your users. If you are unsure on how to do this, please see Restarting Your Server.
5. After the server restart, learners and coaches will be able to switch their language to any of the installed language packs. Their default will be the default that you set by clicking on “Set as default”.

Delete Language Packs¶

To delete language packs:

1. Log in as the administrator.
2. Click the “Languages” link in the navigation bar
3. In the Installed Languages section, there is a button for deletion of each language.

Restarting Your Server¶

If you have made some configuration changes (such as changing the filepath to your video content to your liking), or if you feel the need to reboot your KA Lite system, you may want to restart your server. Please note that this will cause KA Lite to become inaccessible to any users. However, this will not delete any user accounts or information that you have configured during set up.

This process varies, depending on which OS you are running the KA Lite Server on.

Restarting Your Server: Mac¶

1. Open up your terminal. You may do this by navigating to the magnifying glass at the top right corner of your screen, and typing in “Terminal”, then hitting “Enter” on your keyboard.

1. Your terminal should be opened up. It should look a little something like the following:

1. Type in kalite restart. This should stop the server, then attempt to restart it again. The process may take up to a few minutes.
2. Once you see the script that begins with To access KA Lite from another connected computer, try the following address(es): .... you will know that your KA Lite server has been successfully restarted.

Configuration Settings¶

Once you have deployed KA Lite to a computer, there are a number of ways you can customize the behavior of your installation. Below, you will find a list of these possible customizations with instructions or descriptions on how to do it.

from kalite.project.settings.raspberry_pi import *
# Put your settings here, e.g.
# MY_SETTING_VAR = 123

Available settings¶

See above for instructions on where to configure these settings.

from kalite.project.settings.base import *
CONTENT_ROOT = '/example'
DATABASES['assessment_items']['NAME'] = os.path.join(CONTENT_ROOT, 'assessmentitems.sqlite')

Coach Reports¶

Coach reports are visualizations of the data generated by your learners. The goal of the coach reports is to put the data into an easy to understand format, so you can understand how learners are progressing and where they need the most help.

The Report Page displays an overview of the learners and a tabular report.

Tabular Report¶

A tabular report is a grid that can show how students are doing in specific subjects at a high level. As a coach, you can select which group of students you’d like to check progress for, and which subset of videos or exercises you’d like to see reports on. This allows you to easily identify which areas learners are struggling in, as well as which learners are doing well.

Progress By Topic¶

1. Click on the “Show Tabular Report” button.
2. A table should be generated with the data requested.

The color of the rectangles in the table indicate how that student is doing on a particular exercise. The following key explains the color code of the table cells (this information will also be available on the Coach Report page):

	Not Attempted: The student has not attempted the subtopic.
	In Progress: The student has completed a few questions.
	Struggling: The student is struggling on the subtopic.
	Completed: The student has completed the subtopic.

Exporting User Data¶

On the facility management page, you can find the “Export Data” button. If you click this button, you’ll be taken to a page where you can export some user data in CSV format. This is so you can perform analyses on data accumulated in KA Lite using your own methods – in the future such tools may be included in KA Lite itself! You can select which resource you wish to export, and narrow down the list of users to draw data from by selecting facilities and groups. When you have made your selection, click the “Export” button to download a CSV file with the requested data.

Accessing KA Lite¶

There are two ways KA Lite can be used:

1. Set up on a network with one main server, having machines connect to this server. If this is the setup chosen, installation is not necessary on a learner’s computer, as it can be accessible through a web browser with the IP address of the server. Simply copy and paste the server’s IP address into your web browser any time you’d like to access KA Lite. If you are unsure what the address is, please contact your administrator.
2. Installed for single user, on one machine. If you are not accessing KA Lite through a network or wish to run KA Lite on your own computer, please follow the KA Lite Installation Guides first before proceeding with this user manual. Once you have done so, copy and paste the URL given during the installation process into a web browser to access KA Lite (it should be http://127.0.0.1:8008).

How to Sign Up¶

Learners may receive their account information from their Coaches or Administrators if their account has been preconfigured. However, it is possible for learners to create their own account. To create an account, please follow the instructions below:

1. Open KA Lite.
2. Click “Sign Up” at the top right of your screen.
3. If you are redirected to a page that asks you to select a facility, please select the facility to which you belong. If you are unsure which facility you belong to, please contact your administrator or coach. Skip this step if you do not see this page.
4. Fill out the information.
5. Click the “Create user” button when you are finished.

How to Log In¶

1. Open KA lite.
2. Click on the “Log In” tab.
3. Enter your username and password, and then click the “Log in” button.

Navigating through Content¶

To begin engaging with the Khan Academy videos and exercises, first make sure you are logged into KA Lite. Upon log in, you should see a green menu on the left that lists the content. If you do not see this green menu, please start by clicking on the “Learn” tab on the home page.

Start by selecting the subject you’d like to explore. This will expand the side menu, displaying subtopics within that subject.

The icons to the left of the menu selections describe whether or not it is a video, an exercise, or a menu that can be further expanded:

• icons designate that the selection can be further expanded into subtopics
• icons designate that the selection is an exercise for that topic.
• icons designate that the selection is a video for that topic.

Once you have found the video or exercise that you’d like to engage with, simply click on that selection.

How to Practice Exercises¶

First, please log into KA Lite. Then, navigate to the topic that you’d like to practice exercises for.

To answer a question, enter the answer in the box on the top right of the module, or select the bubble next to the answer choice in the exercise panel. Once you have decided on your answer, click “Check Answer”.

After answering a question, the exercise module will not advance to the next question until you click the “Next Question...” button on the right hand side of the module.

The bar on the top right will display your progress as you go through the exercises. After 8 correct answers out of the last 10 answered, your points for the exercise will be added to our total and you will have mastered the exercise. If you get an answer wrong or ask for a hint, you will be unable to earn points from that question until it is presented again.

How to View Your Progress¶

At any point in time, you should be able to view your progress on any topic. In order to do this,

1. Log into KA Lite.
2. Then, click on your name in the top right of the page.
3. It will then show a drop-down menu, from which you can click on “My Progress”.

On the progress page, you will be able to view your progress on each topic. There will be two bars for each topic. The top bar represents your progress on the videos for that topic, and the bottom bar will represent your progress on the exercises for that topic.

Recommended setup¶

KA Lite is like a normal django project, if you have done Django before, you will recognize most of these steps.

1. Check out the project from our github

2. Create a virtual environment “kalite” that you will work in:

   sudo pip install virtualenvwrapper
   mkvirtualenv kalite
   workon kalite
   

3. Install kalite in your virtualenv in “editable” mode, meaning that the source is just linked:

   cd path/to/repo
   pip install -e .
   

4. Install additional development tools:

   pip install -r requirements_dev.txt
   

5. Run a development server and use development settings like this:

   kalite manage runserver --settings=kalite.project.settings.dev
   

You can also change your ~/.kalite/settings.py to point to kalite.project.settings.dev by default, then you do not have to specify –settings=... every time you run kalite.

Now, every time you work on your development environment, just remember to switch on your virtual environment with workon kalite.

Running directly from source¶

KA Lite can also be run as a “source distribution” for development purposes. By this, we just mean a git checkout (from our github).

If you are able to use pip and install conventional python packages from an online source, then the quickest option to install the latest stable release of KA Lite is pip install ka-lite` or `pip install ka-lite-static.

Static vs. Dynamic version¶

Apart from Python itself, KA Lite depends on a couple of python applications, mainly from the Django ecology. These applications can be installed in two ways:

• Dynamic: That means that they are automatically installed through

  PIP as a separate software package accessible to your whole system. This is recommended if you run KA Lite and have internet access while installing and updating.

• Static: Static means that KA Lite is installed with all the external

  applications bundled in. Use this method if you need to have KA Lite installed from offline media or if KA Lite’s dependencies are in conflict with the system that you install upon.

Virtualenv¶

You can install KA Lite in its very own separate environment that does not interfere with other Python software on your machine like this:

$> pip install virtualenv virtualenvwrapper
$> mkvirtualenv my-kalite-env
$> workon my-kalite-env
$> pip install ka-lite

Purpose¶

Our Backbone Models and Views can end up having a lot of methods. It is important that all of those methods observe the correct input output characteristics. Hence it is important that we write tests that guarantee that our methods either take the correct input and produce the right output, or, as is often the case, produce the right side effects on models, views, or the DOM.

In pursuit of this lofty goal of having every method and object testable and tested, there will be some requirements of refactoring along the way. Some of the code that has already been written for the KA Lite project is not conveniently parcelled in such a way as to be conducive to testing individual components in an atomic fashion. In order to ensure that functionality does not break as a result, we have integration tests (which are currently only implemented using Selenium scripted by Python) - for now we are avoiding writing such integration tests in Javascript as well so as to avoid duplication.

Setting up your Test Environment¶

1. Install requirements:

   • install node if you don’t have it already.
   • install pip if you don’t have it already.

2. Install the dependencies listed in requirements.txt: pip install -r requirements.txt

3. Install the dependencies listed in packages.json: sudo npm install

Getting Your Javascript to be Testable in KA Lite¶

Before you can test your javascript, it must be capable of being bundled in such a way that django-compress (the asset compression package we use) is able to write it to a Javascript file which can then be loaded by the Javascript test runner, karma.

In order to make this happen, use compression tags around blocks of Javascript script imports inside django templates for example, from learn.html:

{% compress js file learnjs %}
<!--[if !IE]> -->
<script src="{% static "video-js/video.js" %}"></script>
<script src="{% static "video-js/video-speed.js" %}"></script>
<script>
    _V_.options.flash.swf = window.flash_swf;
</script>
<!-- <![endif]-->
<script src="{% static "soundmanager/soundmanager2-nodebug-jsmin.js" %}"></script>

<script src="{% static 'js/distributed/content/models.js' %}"></script>
<script src="{% static 'js/distributed/content/views.js' %}"></script>

<script src="{% static 'js/distributed/video/models.js' %}"></script>
<script src="{% static 'js/distributed/video/views.js' %}"></script>

<script src="{% static 'js/distributed/audio/views.js' %}"></script>

<script src="{% static 'js/jquery.slimscroll.min.js' %}"></script>
<script src="{% static 'js/distributed/topics/models.js' %}"></script>
<script src="{% static 'js/distributed/topics/views.js' %}"></script>
<script src="{% static 'js/distributed/topics/router.js' %}"></script>

{% endcompress %}

You will also need to inclue the tag {% load compress %} at the top of a template in order to make use of the compress template tag.

Let’s examine the important details of {% compress js file learnjs %} - the compress tag name is followed by the kind of file being compressed (js), then two optional parameters. The first tells django-compress to compress the assets to a separate file (rather than rendering the concatenated Javascript inline in the HTML), the second gives a name to the code block. This should be a unique name across the entire code base. At current there is no way to know what names have already been used, except by examining karma.conf.js in the root of the project.

The name of the block is important for making it available for Javascript testing - it needs to be manually added to the karma.conf.js here:

// list of files / patterns to load in the browser
files: [
  file_map['basejs'].slice(1),
  file_map['perseusjs_1'].slice(1),
  file_map['perseusjs_2'].slice(1),
  file_map['learnjs'].slice(1),
  file_map['pdfjs'].slice(1),
  // INSERT NEW JAVASCRIPT BUNDLES HERE
  '**/tests/javascript_unit_tests/*.js',
  'testing/testrunner.js'
],

So if you had created a new compression block called ‘exparrotshop’ then you would add the element file_map['exparrotshop'].slice(1) to the array.

Writing a Test¶

You are now ready to write a test. All Javascript unit tests live inside the appropriate app. For example, if you were writing a unit test for Javascript code for the coachreport app, you would put your test file in kalite/coachreports/tests/javascript_unit_tests/. Call your file the name of the Model, View, or Router you are testing, or use an existing test file if you are extending an already tested Model or View. For example, the Session Model test file is called:

session_model_test.js

Each test file should start with a definition statement:

module("Session Model Tests", {
  setup: function() {
    return this.sessionModel = new SessionModel();
  }
});

The text gives the name of the suite of tests you will be writing in this file. The setup method defines something that happens prior to every single test being run. this gets returned to every subsequent test as this also, so anything set as an attribute of this will be available inside each test.

After the module definition, you can define any number of tests. Here is a simple example:

test("Default values", function() {
  expect(2);

  equal(this.sessionModel.get("SEARCH_TOPICS_URL"), "");
  equal(this.sessionModel.get("STATUS_URL"), "");
});

This simple test is checking the default values for the Session Model defined during the setup method above. At the beginning of the test, we declare how many assertion statements will be made during the course of the test. Not specifying this number correctly will cause a failure. The tests are written in QUnit whose docs can be referred to for a complete set of assertions.

Running Tests¶

When you have written your tests, before you can run them, we need to bundle the Javascript for testing. In order to do this, from the root of the project run:

bin/kalite manage bundleassets

This will bundle all the django-compress tags and make concatenated files. It will also update the file_map that our Karma config uses to find these files. When this is complete, simply run:

karma start

This will run through all the Javascript tests and report on failures. N.B. Karma is often, and most helpfully, run in continuous integration mode - our code base does not currently suppor that, but hopefully will in the future.

Running the integration tests¶

To get the dependencies run `pip install -r dev_requirements.txt`. This should install the correct version of behave. Selenium is also required but is currently included in our python-packages directory.

To run the tests simply run `python kalitectl.py manage test` just like you used to. This will automatically search out tests using both the unit test framework and the behave framework. You can specify apps, but right now there’s no way to just run integration tests.

Anatomy of the integration tests¶

The test command will look inside each app for a `features` directory. Inside that directory should be one or more `[name].feature` files written in the Gherkin specification language. See the behave docs for more details on Gherkin, or look in the `control_panel` app, where your humble author has attempted to provide some examples.

The test runner will parse the `.feature` files and attempt to build a test suite from step specifications found in any python files (the name is irrelevant) in the `steps` subdirectory. There is a 1-to-1 mapping between the clauses you write in the Gherkin specification and the steps you implement, so it can save you time to reuse clauses. Steps can also be templated to match clauses that follow a pattern.

You can also set up the test environment at key stages in the testing process by writing hooks in an `environment.py` file in the `features` directory. In the `control_panel` example, the `before_feature` function is defined to log the testing user in as an admin before each feature tagged with the `@as_admin` tag in the specification. In `testing/base_environment.py`, the `before_all` and `after_all` hooks are defined to set up a Selenium WebDriver instance on the context object that is passed around by the test runner. This file is intended to be used as a base for all the integration tests, so if there is some setup common to all integration tests then put it there. You can then import those functions in the `environment.py` of specific apps, and extend or overwrite as necessary.

Finally, in `testing/behave_helpers.py` you’ll find various functions that should be generally useful for all integration tests. If you find yourself wishing you had a nice useful function, add it here. In order to avoid reproducing functionality while we phase out the old integration tests, if some functionality already exists in the form of a mixin, you should import it into that file and wrap it in a new function. Be very reticent about importing mixin code! A good rule of thumb is to glance at how something is implemented in the mixins first, and only import it if it’s not trivial to reproduce. Only re-write if there’s no chance of the new code producing an error! The main goal is to avoid maintaining two sets of code.

Suggested workflow for writing new features¶

Ideally you should:

1. Specify your integration tests.
2. Write failing steps.
3. Write code that makes your tests pass.

In practice, at least try to specify the tests first. Then you can seek out assistance implementing the steps.

Selenium gotchas (aka race conditions)¶

Finding elements on the page can be subject to race conditions if the page is not yet completely loaded, or if the DOM changes in response to AJAX stuff. Selenium pprovides methods for finding elements with and without explicit waits. When in doubt, use a wait. If your app is AJAX-y, write testable code by putting in events or flags that Selenium can explicitly wait for. The Selenium `get` method of browsing will wait for the page to fully load. Do not assume that following links using e.g. the `click` method will wait for the page to load – it does not. To summarize:

1. Incorporate explicit flags in your code that Selenium can use in waits.
2. Don’t use unsafe methods that don’t wait unless you’re 100% certain there’s no possibility for a race condition.

Getting a general overview of resources used¶

To get a sense of the resources used by KA Lite over a period of time, run the kalite command with the PROFILE environment variable:

PROFILE=yes kalite <command>

Upon normal exit, the program will write to a file called memory_profile.log containing the time and resource utilization. For now we only log memory usage.

Django Management Commands¶

All Django management commands can be run by typing:

kalite manage <command_name>

in the root directory of the KA Lite project.

generaterealdata¶

This function is designed to produce example user data for testing various front end functionality, such as coach reports and content recommendation. It does take some shortcuts, and will not produce accurate answer data for exercises. This is a Django management command and can be run with the following command:

kalite manage generaterealdata