Current version 1.0.5 --- built Mon Aug 26 15:31:57 EDT 2013.

JLSCircuitTester is an extension to the JLS digital logic simulator that allows users to automatically test circuits (including CPUs) constructed using JLS. Our main goals for this project are to

  1. encourage students to more thoroughly test their circuits by simplifying the generation and running of tests; and
  2. save instructors time by automating the testing of student circuits.
Our ITiCSE paper discusses our successes achieving these goals.

To test a circuit, users run a command-line program named jlsCircuitTester that takes (1) the file name of the JLS circuit under test and (2) the name of a script describing one or more input sets. (A input set lists the desired input for each input pin, register, and memory object.) For each input set, jlsCircuitTester simulates the circuit under test, compares the observed results (output pins, registers, and memory) to the expected results, and reports any discrepancies.

For CPUs, users run a command-line program named jlsCPUTester that takes (1) the name of the .jls file under test and (2) the name of a MIPS assembly file. The program then assembles and simulates the assembly file and compares the final states of the registers and memories to those of the simulated CPU.


In addition to automatically comparing the observed results to the expected results, JLSCircuitTester has several features that make it easy to quickly write a thorough set of tests:
Named value lists
Users can specify several input sets at one time by providing a list of values for a given input pin. These lists can be given a name and used in several tests.
Programmed value lists
JLSCircuitTester also provides some "programmed" lists of common test cases including ranges, "corner cases" (e.g., values around powers of 2), "templates" (e.g., the eight values that match the pattern 1???0), and random values.
The ability to use Java classes to compute expected output values.
Users can specify the expected simulation results in one of two ways: First, they can simply list the expected results along with the desired inputs for each test. This technique works well for simple circuits like a half adder. (See this example input file.) However, listing the output can become tedious for more complex circuits (e.g., ALUs or CPUs). Thus, JLSCircuitTester allows users to specify a Java class to compute the expected results. This technique is especially useful (1) in combination with input sets specified using value lists, and (2) when testing CPUs.
Extensibility: It is not possible to imagine all the different ways instructors will use JLS in the classroom, and all the resulting assignments. Therefore, we designed JLSCircuitTester to be easily extensible. We expect the most common extension will be the addition of new Java classes to compute a circuit's expected result (e.g., a counter, or a new textbook's pedagogical CPU). In addition, we provide for the addition of new input formats (i.e., different syntax for specifying a circuit's inputs and initial state). We plan to eventually support the addition of new programmed value lists. Finally, we believe that the JLSCircuitTester framework is designed well enough that instructors could even write their own "main" program, if desired. (This extensibility will be useful, for example, if an instructor wanted to be more precise about the order in which tests are run, or wanted to allow for one of several possible outputs for a given input.)


To use JLSCircuitTester, download the following components:

You can also use JLSCircuitTester to test MIPS-like CPUs (i.e., the CPU simulated by SPIM and MARS). To test CPUs you must also download

Alternately, JLSCircuitTester.tar contains all of the aforementioned files.

Basic Usage

To test "ordinary" circuits:

To test MIPS-like CPUs:

Full Documentation


The following are my JLS-related assignments for Fall 2007:

Future Work

Request For Comments


Thanks to


Last modified: Wed Jan 16 10:11:39 EST 2008