Galah Interact

This is the main documentation for the Galah Interact project. The contents of this site are automatically generated via Sphinx based on the Python docstrings throughout the code and the reStructuredText documents in the docs/ directory of the git repository. If you find an error in the documentation, please report it in the bug tracker here (which we share with the Galah project), or even better, submit a pull request!

What is Galah Interact

Galah Interact is a library designed to make it very easy to create Test Harnesses that grade student’s assignments. It provides code to perform a number of tests that many instructors care about (such as checking that code is properly indented, or that code compiles without any warnings) along with providing utilities to make more complicated testing much easier (unit testing for example is extremely easy with this library, as you can simply import all of the student’s functions and classes into Python).

The reason for Galah Interact’s creation was to make it easier to create Test Harnesses for Galah, however, we don’t have any intention on locking in this library’s use (this is why we’ve released it under the very permissive Licensing). The real goal of Galah Interact is to provide a powerful framework for creating excellent test harnesses no matter what the submission system you are using for your class is.

Galah Interact can only test C++ code right now. We would really like to support other languages as well, so if you are interested in using this library at your university that teaches using a different language, please let us know so we can work with you.

Tutorials, Examples, and Guides

If you have not used this library before, you should start your journey by going through these tutorials.

• Getting Started
  • Step 1 - Installing Galah Interact
  • Step 2 - Hello World
• Unit Testing
  • Basic Unit Testing
  • Using the interact.capture module

Reference Material

To get documentation on a specific function or module, or if you just want to browse through all of what Galah Interact has to offer, check out the below pages.

• Interact Framework
  • interact.core
  • interact.execute
  • interact.parse
  • interact.pretty
  • interact.standardtests
  • interact.unittest
  • interact.capture
• Test Harness Command Line Interface
  • Basic Usage
  • Execution Modes
  • Configuration Values

Quick Sample

To give you an idea of what using this library feels like, below is a simple but fairly complete test harness for an assignment where the students must make a foo() function that takes in two numbers and returns their sum.

teaser.py

#!/usr/bin/env python

import interact

harness = interact.Harness()
harness.start()

student_files = harness.student_files("main.cpp")

@harness.test("Proper files exist.")
def check_files():
  return interact.standardtests.check_files_exist(*student_files)

@harness.test("Program compiles correctly.", depends = [check_files])
def check_compilation():
  return interact.standardtests.check_compiles(student_files)

@harness.test("Proper indentation is used.", depends = [check_files])
def check_indentation():
  return interact.standardtests.check_indentation(student_files)

@harness.test("foo function works correctly.", depends = [check_compilation])
def check_foo():
  result = interact.TestResult(
    brief = "This test ensures that your `foo` function correctly takes in two "
            "integer parameters and returns their sum.",
    default_message = "**Great job!** Your function works great!",
    max_score = 10
  )

  student_code = interact.unittest.load_files(student_files)

  if "foo" not in student_code["main"]:
    result.add_message("You didn't create a `foo` function.", dscore = -10)
    return result.calculate_score()

  foo = student_code["main"]["foo"]
  try:
    if foo(3, 4) != 7:
      result.add_message("Your function did not give the correct sum.")
  except TypeError:
    result.add_message("Your function does not have the correct signature.")

  return result.calculate_score(min_score = 0)

harness.run_tests()

harness.finish(max_score = 31)

When running this harness with ./teaser.py --mode test, and a correctly implemented main.cpp (example here), the following is output:

Score: 1 out of 1

This test ensures that all of the necessary files are present.

Great job! All the necessary files are present.
-------
Score: 10 out of 10

This test ensures that your code compiles without errors. Your program was compiled with g++ -o main /home/john/Projects/galah-interact-python/docs/guides/examples/teaser/main.cpp.

**Great job!** Your code compiled cleanly without any problems.
-------
Score: 10 out of 10

This test checks to ensure you are indenting properly. Make sure that every time you start a new block (curly braces delimit blocks) you indent more.

**Great job!** We didn't find any problems with your indentation!
-------
Score: 10 out of 10

This test ensures that your `foo` function correctly takes in two integer parameters and returns their sum.

**Great job!** Your function works great!
-------
Final result: 31 out of 31

Licensing

The code is licensed under the Apache 2.0 license, which is a very permissive license. You can read a summary of its specific terms on the wikipedia page for the license here. The entire license text is also contained within this repository if you’d like to read the license itself.

In short, the license is very permissive and lets you do basically whatever you want with the code as long as you properly attribute the contributers. So as long as you don’t rip out the code and say you wrote it, your probably staying within the terms of the license.

Note that this license is very different than the license that covers Galah itself. Please don’t confuse the two.