Teacher Test Repository
=======================

**Official Test Respository**: `fork/clone me <https://bitbucket.org/yeukhon/teacher-test-repo>`_

Yes. Just use this as your starting point. We even included
a basic **.hgignore** for you.

.. _test-repo-structure-label:

Test Repo Structure
-------------------

.. code-block:: bash

    top-level-repo-folder
        - config.yaml
        - runner.py
        - test_<name>.py
        - any other files
        - any other folders/*


config.yaml
~~~~~~~~~~~

This is Aurum's test repo configuration file. It describes
how Aurum uses your test code to run against students' input.

See :ref:`config_yaml` for configuration details.

Here is an example:

.. include:: exercise_configuration.rst
   :start-after: begin-python-config
   :end-before: end-python-config


.. warning::

    Do not use TAB in any YAML file because it will raise
    error when YAML tries to parse the file. Use spaces!


runner.py
~~~~~~~~~

This file is required because this is the main program Aurum runs. 
It basically tells Aurum to execute ``nosetest`` and make a report
afterward.

You can find this in the official repository at the end of this page.

.. _unittest-warning-label:

test_<name>.py
~~~~~~~~~~~~~~

This contains the test code written in Python using the `unittest <http://docs.python.org/2/library/unittest.html>`_ module. We then use `nosetest <http://readthedocs.org/docs/nose/>`_ to run the test code and generate a report from the test result.

The sample teacher test repo above has one test file called ``test_c_exercise.py``:

.. warning::

    The current Aurum system is running on Python 2.6.5. Therefore, certain `unittest <http://docs.python.org/2/library/unittest.html>`_ features are not present in that module. You have to use ``unittest2``. We have this module installed but to make things simpler, if you need to run on both 2.6.5 and 2.7+, you should consider doing:

    .. code-block:: python

        try:
            import unittest2 as unittest
        except ImportError:
            import unittest

If you use our official test repo above, we include this for you.


.. _test-repo-samples-label:

Full Examples
-------------

We have compiled some fully working, non-trivial examples
for you to look at.

Python: 

    **find_evens**: `bitbucket <https://bitbucket.org/yeukhon/simple-python-teacher-test-repo>`_


Best Practices
--------------

We consider these as best practices to avoid problems such as 
cheating in a smart way. The things we mention here will
reference options in ``config.yaml`` and writing unittests.

1. If you want to commit your solution in the respository,
   avoid using common file names such as ``soln.py`` or 
   ``solution.py`` (or **.cpp**, you get the point here). 

   This is a big issue in Python because you can import 
   the solution. There are some workarounds such as
   adding directories so students have to guess where
   the actual solution lives. This is obviously 
   tedious work. If you plan on  making the test code public,
   you have to work around by
   deleting (or even mocking out) the import at run time.

   We **actually** do encourage you to commit your solution
   code because you can version control it. Just don't use
   common names!

2. Use ``try: import xx except: ...`` unittest method 
   we recommend in a section or two above. Use that. 

3. Avoid committing large files such as data. They should
   live somewhere else. For example, Dropbox or Google
   Drive. If you have to commit a few images, that's fine.
   If you have more than a few images or very complex csv files,
   try hosting them somewhere else. Or talk to us. We can
   sort out the most practical way to do this with you.

4. Do not forget your **.hgignore** file. See :ref:`include-hgignore-label`.

5. Do not forget to perform some cleanup in your tests. Very often 
   the assignments may involve some file generations that
   are useless afterward (i.e. download a sample csv file
   so student code can run against this file) because they
   don't count toward student's result, then you should perform
   ``tearDownClass`` in your unittest test case.

.. note::

    We recommend you fork / clone our `oficial respository <https://bitbucket.org/yeukhon/teacher-test-repo>`_ on Bitbucket.