Menu

Theme

Advanced features · How-to · CHECKED ON 5.0.0

How to test a circuit in Logisim with test vectors

Here is how to test a circuit in Logisim: write a test vector, a text file with the pin names on the first line and one row of inputs and expected outputs per test, then load it with Simulate, Test Vector…. From the command line, --test-vector prints Passed: N, Failed: M but always exits with code 0 in our tests, so an autograder must read that line. It also needs a display (use Xvfb on a server).
FOR
Students told to pass a test vector, and teachers building an autograder · Logisim-evolution 5.0.0
CHECKED
12 Nov 2026
FIX TIME
about 10 min
Checked against Logisim-evolution 5.0.0 on 5 machines
On this page

Our failing run, from the Linux lab on 11 Nov 2026 with the official 5.0.0 jar (F17):

Terminal (Linux, under Xvfb)
java -jar logisim-evolution-5.0.0-all.jar -w main vectors/full-adder-fail.txt circuits/full-adder-v5.circ
Output: Loading test vector “vectors/full-adder-fail.txt”…
Output: Running 8 vectors…
Output: 1 2 3 4 5 6 7 8
Output: Error on test vector 8:
Output:   S = 1 (expected 0)
Output: 
Output: Passed: 7, Failed: 1
echo $?
0

The same exit code 0 appeared on Linux, GitHub-hosted Windows Server 2025, Windows 11 ARM64, and macOS 15 on Apple Silicon and Intel. These are the systems we could reach, not every machine a course uses. Re-check it after each release.

How to test a circuit in Logisim: run a test vector in the GUI

  1. Open the circuit

    The test runs on the circuit that is current in the project window. Open your .circ file and select the circuit your vector is written for.

    Check: The circuit you want to test is in the window.

  2. Open the Test Vector window

    Choose Simulate, Test Vector…. It starts empty and reads “Selection is empty.” (F105).

    Check: A small window with Load Vector, Run, Stop, Reset and Close Window.

  3. Load the vector

    Press Load Vector and pick your file. The file chooser is filtered to “Logisim-evolution Test Vector (*.txt)”.

    Check: A file chooser listing .txt files.

  4. Read the result

    Logisim ran every row as soon as we loaded the file. The header shows the counts. A failing row is listed first and its wrong output cell is shaded red.

    Check: The header shows Passed and Failed counts.

LAB lab-lnx · Linux lab5.0.02026-11-12

The Test Vector window: the header reads Passed: 8 Failed: 0. A table has Show and Set buttons per row, a Status column where every row says pass, the columns <set> 0 and <seq> comb, then the pins A, B, Cin, S and Cout with the eight rows of the full adder. Buttons below: Load Vector, Run, Stop, Reset, Close Window.

Simulate, Test Vector with our passing full adder vector loaded: Passed: 8, Failed: 0. Linux lab, Logisim-evolution 5.0.0.lab-lnx-le500-test-vectors-01
Test Vector window: Passed: 8 Failed: 0, with the eight rows of the full adder all marked pass.
LAB lab-lnx · Linux lab5.0.02026-11-12

The Test Vector window with the header Passed: 7 Failed: 1. The first row says fail and its S cell is shaded red with the value 1 while Cin, A, B are all 1; the other seven rows say pass.

The same window with our failing vector: the failing row is listed first and the wrong output cell is red. Linux lab, Logisim-evolution 5.0.0.lab-lnx-le500-test-vectors-02
Test Vector window with Passed: 7 Failed: 1; the failing first row has its S cell shaded red.

Each row has a Show button and a Set button. We did not press them, so we describe nothing about what they do to the canvas. We also did not test hover text on a red cell.

To practise, download the full adder, the passing vector and the failing vector, where row 8 is wrong on purpose. Both vectors are the ones we used for the screenshots above.

The file format

Our passing vector for the full adder. The first line after the comment names the pins; every other line is one test:

File full-adder.txtvector
# full adder, all 8 rows (logisim.dev lab)
A B Cin S Cout
0 0 0 0 0
0 0 1 1 0
0 1 0 1 0
0 1 1 0 1
1 0 0 1 0
1 0 1 0 1
1 1 0 0 1
1 1 1 1 1
Test vector format rules
CommentsA line starting with # is ignored. Our file above has one and passed 8 of 8.Tested (F17 run)
Header lineOne name per column, the same as the pin labels, including capitals. s does not match a pin labelled S: the run stops with “Column S has no matching pin”. A trailing space in the label did not matter.Tested (F38, F102)
Multi-bit pinsWrite the width in brackets, for example Q[4]. A one-bit column against a two-bit pin stops with “Column S has width 1 but pin has width 2”.Tested (F102)
HexadecimalStart with 0x, for example 0xF. A capital 0X was rejected.Tested (F38)
DecimalThe value must fit the column as a signed number: 15 in a 4-bit column was rejected (“Too many bits”).Tested (F38)
BinaryDigits equal to the width, for example 0101 in a 4-bit column.Used in our vectors; wrong-length case not tested
Don't care<DC> in an output column accepts any value, at any width. A bare x is only a per-bit don't care inside a binary value, and on an 8-bit column it is rejected.Tested (F72, F104)
Floating<float> as an expected output means the pin must be floating. Our buffer row with the buffer off passed with <float> and failed with an expected 0 (“Y = U (expected 0)”).Tested (F104)
Extra or missing valuesOne value too many on a row is rejected (“too many values”).Tested (F38)
Underscores in numbersNot tested here.Not tested

Not sure about your file? Build and check your vector in the browser.

Sequential circuits: set and seq

By default every row is its own test: Logisim resets the circuit before each row. A flip-flop therefore forgets its state between rows. Our 14-row flip-flop vector passed only 3 rows that way, and all 14 once we added the two extra columns (F65).

Add the columns <set> and <seq> at the end of the header. Rows with the same <set> number belong together and run in <seq> order with no reset between them. The first step of a set starts from a reset; each later step starts with one simulation tick. A row with <set> 0 and <seq> 1 is rejected (F38). The upstream guide inside the jar describes the same rule.

Our 4-bit counter vector gives the clock as an input pin called CLK, one row for the low half and one for the high half of each cycle:

File counter-seq.txt (first rows)vector
CLK Q[4] <set> <seq>
0 0x0 1 1
1 0x1 1 2
0 0x1 1 3
1 0x2 1 4
0 0x2 1 5
1 0x3 1 6
CLK and Q for the first six steps of the counter vector (F105)
Show values as a table
stepCLKQ
000
111
201
312
402
513
LAB lab-lnx · Linux lab5.0.02026-11-12

The Test Vector window for the counter vector with the header Passed: 41 Failed: 0, scrolled to the last rows. Columns: Show, Set, Status, <set> 1, <seq> from 27 to 41, CLK alternating 1 and 0, and Q in hex counting d, e, f, 0, 1, 2, 3, 4.

A sequential vector: every row is in set 1 and has its own step number, so the counter keeps its state from row to row. The list is scrolled to the end. Linux lab, Logisim-evolution 5.0.0.lab-lnx-le500-test-vectors-03
Test Vector window for the counter, Passed: 41 Failed: 0, scrolled to the last rows.

All 41 steps passed in the GUI and on the command line. Download the counter and its vector.

A Clock component works too, but then there is no CLK column: the vector lists only outputs, and each step after the first moves the clock by half a cycle. A 6-step vector with outputs 0x0 0x1 0x1 0x2 0x2 0x3 passed on a counter with a Clock component, and a CLK column on it was rejected (F104). We published the input-pin version because the vector then states the clock value on every row.

Classic Logisim 2.7.1 has no test vectors: its -help lists no such option and its jar holds no test vector class (F106). See the classic 2.7.1 guide.

Floating and don’t-care outputs

Our controlled buffer passes input A when E is 1 and leaves Y floating when E is 0. The vector uses <float> for the floating rows and <DC> for a row where we accept anything:

File tristate.txtvector
# controlled buffer: E=1 passes A, E=0 leaves Y floating
A E Y
0 1 0
1 1 1
0 0 <float>
1 0 <float>
1 0 <DC>

Download the buffer circuit and its vector. All five rows passed (F104).

Generate a vector from a log

Two Logisim windows write tables you can start from: the timing diagram window and Combinational Analysis. Neither writes a file that is guaranteed to load as a vector, so run the result through the checker before you rely on it.

Run test vectors from the command line

The option is -w or --test-vector, followed by the circuit name, the vector file and the circuit file (F01). The installed launchers accept command-line options too (F28, tested with –version and –tty); for a grader we recommend the jar, because the command is the same on every system.

On Windows

Command Prompt
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ

On macOS

Terminal (macOS)
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ

On Linux

Terminal (Linux, desktop)
java -jar logisim-evolution-5.0.0-all.jar --no-splash --test-vector main full-adder.txt full-adder.circ

On a server with no display, put xvfb-run -a in front of java.

The output is a line for each loaded vector file, one progress number per row, an “Error on test vector N:” block for each failure naming the pin, the actual value and the expected value, and a last line Passed: N, Failed: M.

What 5.0.0 printed and returned in our runs
Vector passesPassed: 8, Failed: 00F17, F92
Vector failsError on test vector 8: then Passed: 7, Failed: 10F17, F92
Header name or width does not matchError preparing test vector: Column S has no matching pin0F102
Circuit name not in the fileCircuit 'nosuch' not found.0F92, F102
Circuit file missingan ERROR line from Startup255F92, F102
Classic 2.7.1 file, empty file, damaged file, unknown librarynothing: a dialog waits for a clicknone (hangs)F102
No displayjava.awt.HeadlessException1F18
<code>-b</code> test bench, passTest bench pass0, from the code in the jar; not runF103
<code>-b</code> test bench, failTest bench fail255 (-1), from the code in the jar; not runF103

The -b or --test-circuit option is a different feature: it looks for a circuit named logisim_test_verif with output pins test_bench_done_o and test_bench_ok_o and waits for both to be 1. We built four such files and none of them finished on our lab machine: a folder chooser for a simulator path stayed open (F103). We therefore do not recommend it for grading, and the two exit codes above come from reading the jar, not from a run. The older option name -testvector is not in the 5.0.0 help.

LAB lab-lnx · Linux lab5.0.02026-11-12

A folder chooser with Look In set to root, an empty list, Folder name /root, Files of Type All Files, and the buttons Select and Cancel.

The folder chooser that stays open when -b is run on our test bench files, Linux lab under Xvfb (F103).lab-lnx-le500-bench-folder-chooser-01
A folder chooser dialog with a Folder name field, an empty list and Select and Cancel buttons.

Autograder recipe

We ran 30 student-style variants of the full adder through this recipe (F102). The recipe gave the right verdict on every one. Steps:

  1. Put Java 21 and the jar in the image

    Use the jar from the download page. Pin the version your course uses (which version). On Ubuntu or Debian the installer package also works, see Linux install.

    Check: java -version prints 21.

  2. Install Xvfb

    –test-vector needs a display, so wrap it in xvfb-run -a.

    Check: xvfb-run is on the PATH.

  3. Run each submission with a time limit

    Five of our 30 files opened a modal dialog and would have waited forever. A limit of 30 seconds was far above the 1 second a normal run took.

    Check: A file that opens a dialog is killed, not waited for.

  4. Decide from the text

    Pass needs: a line Passed: N, Failed: 0; N equal to the number of rows in the vector; no word “Exception” in the output. Everything else is a fail. Never use the exit code.

    Check: Pass only when every condition holds.

  5. Check the pin types of any suspicious pass

    An output pin changed to an input passed 8 of 8 in our run. If you grade strictly, also parse the submitted .circ and confirm the pin directions (the .circ viewer lists them).

    Check: Output columns are output pins.

The recipe as one script, the same file as the download:

File autograde-logisim.shbash
#!/usr/bin/env bash
# Usage: autograde-logisim.sh <jar> <circuit-name> <vector.txt> <circuit.circ> [timeout-seconds]
jar=$1; circuit=$2; vector=$3; file=$4; limit=${5:-30}
expected=$(grep -Ev '^[[:space:]]*(#|$)' "$vector" | tail -n +2 | wc -l)
out=$(timeout -k 5 "$limit" xvfb-run -a java -jar "$jar" --no-splash -w "$circuit" "$vector" "$file" 2>&1)
code=$?
[ "$code" -eq 124 ] || [ "$code" -eq 137 ] && { echo "FAIL timeout after ${limit}s"; exit 1; }
summary=$(printf '%s\n' "$out" | grep -E '^Passed: [0-9]+, Failed: [0-9]+' | tail -n 1)
[ -z "$summary" ] && { echo "FAIL no summary line (exit $code)"; exit 1; }
passed=${summary#Passed: }; passed=${passed%%,*}; failed=${summary##*Failed: }
printf '%s\n' "$out" | grep -q 'Exception' && { echo "FAIL exception in output"; exit 1; }
[ "$failed" -ne 0 ] && { echo "FAIL $summary"; exit 1; }
[ "$passed" -ne "$expected" ] && { echo "FAIL passed $passed rows, vector has $expected"; exit 1; }
echo "PASS $summary"; exit 0

Download autograde-logisim.sh. Gradescope and GitHub Actions run the same script inside a container with Java and Xvfb installed; we did not run either service, so we give no service-specific steps.

What our 30 files did, by class:

30 student-style variants, 5.0.0, Linux lab (F102)
Passed 8, Failed 010correct file; extra input or output pin; label with a trailing space; header saying 3.8.0 or 9.9.9; CRLF line endings; byte-order mark; no main attribute; output pin turned into an input
Summary with failures7wrong gate (two files); outputs swapped; output or input unconnected; a constant fighting an output; a ring of three inverters
No summary line, exit 0 or 2558label <code>s</code> or <code>CIN</code>; missing pin; circuit not named <code>main</code> (two files); a 2-bit output pin; main circuit with no pins; file missing
Hangs on a dialog5classic 2.7.1 format file; empty file; plain text; truncated XML; unknown built-in library
LAB lab-lnx · Linux lab5.0.02026-11-12

A modal error dialog on a grey background with a red X and the text "16-empty-file: XML formatting error: org.xml.sax.SAXParseException; lineNumber: 1" and the buttons Copy error and OK.

The dialog that stops a command-line test vector run on an empty .circ file, Linux lab under Xvfb (F102).lab-lnx-le500-vector-run-empty-file-dialog-01
Error dialog for an empty circuit file: XML formatting error, with Copy error and OK buttons.
LAB lab-lnx · Linux lab5.0.02026-11-12

A warning dialog: You are opening a file created with original Logisim code. You might encounter some problems in the execution, since some components evolved since then. Moreover, labels will be converted to match VHDL limitations for variable names. One OK button.

The dialog that stops a command-line run on a classic 2.7.1 format file until someone clicks OK, Linux lab under Xvfb (F102).lab-lnx-le500-vector-run-classic-dialog-01
Warning dialog: you are opening a file created with original Logisim code; labels will be converted.

Not covered by our run: a file saved by 4.1.0, a design that cheats with a lookup table, and a circuit that makes the simulator hang. For a comparison without a display, --tty table prints the whole truth table of a combinational circuit and works headless; see the command-line reference. More on running a course: teachers and courses.

Checklist before you submit

Before you submit0 / 5 done

Related pages: the full adder project has its own vectors, and subcircuits explains setting the main circuit.

Frequently asked questions

How do I test a circuit in Logisim?

Write a test vector file, open your circuit, choose Simulate, then Test Vector, and load the file. Logisim runs every row and shows pass or fail, with wrong output cells in red (F105).

What is the test vector file format?

The first line lists pin names exactly as labelled, a multi-bit pin as Name[width]. Every other line holds one value per column. Lines starting with # are comments. See the format section above (F38, F72).

Can test vectors test sequential circuits such as counters and flip-flops?

Yes, with a set column and a seq column. Rows in the same set run in seq order and keep their state; without those columns the circuit is reset before every row (F65). Our 4-bit counter passed 41 steps (F105).

Why does my autograder say pass when tests fail?

Logisim-evolution 5.0.0 exits with code 0 even when a vector fails, and also when the vector file cannot be loaded. Read the Passed line, not the exit code (F17, F102).

Why does --test-vector crash with HeadlessException?

It needs a display. Run it under Xvfb on a server, for example with xvfb-run (F18).

Does classic Logisim 2.7.1 support test vectors?

No. Its help lists no such option and its jar contains no test vector class (F106). The feature is in Logisim-evolution.

Sources

  1. Test vector guide inside the Logisim-evolution 5.0.0 jar (sequential tests), Logisim-evolution project, logisim.dev lab data: doc/en/html/guide/test_vector/ in logisim-evolution-5.0.0-all.jar, accessed 11 Nov 2026
  2. Command-line exit codes and messages, logisim.dev lab data: test-data/FINDINGS.md F17, F18, F92; test-data/lab11-2026-11-11-cli/logs/
  3. 30 student-style files run through the autograder script, logisim.dev lab data: test-data/lab17-2026-11-12-test-vectors/datasets/autograder.csv (F102)
  4. Test Vector window and test bench runs, logisim.dev lab data: test-data/FINDINGS.md F103, F104, F105

Try: , , ,