Z80

Test suites for Zilog Z80 CPU emulators.

Getting Started

Start by installing the NuGet package into your test project:

dotnet add package MrKWatkins.EmulatorTestSuites.Z80

You will then need to create a concrete implementation of the Z80TestHarness Class abstract base class. This is how you wrap up your emulator and expose it through a common interface to the test suites.

Lastly, you will need to add some unit tests in the framework of your choosing. These will be simple calls to the test suite methods. Every test suite has a method to get the available test cases, and each test case has an Execute method to run the test.

Test Suite Types

There are two types of test suite available, instruction and program.

Instruction Test Suites

Instruction test suites contain tests for a single instruction at a time. For example, the DAA test suite just tests the DAA instruction, whereas the Fuse test suite has tests for every Z80 instruction, including the undocumented ones.

By default, the test suites will check everything in the emulator; registers, flags, interrupt properties, memory, IO access and the individual processor cycles. This may not be suitable for your emulator, especially if you've just started; you might not want to test the undocumented flags to start with, for example. The assertions to run can be controlled via the TestAssertions Enum enum, which is a flags enum covering all the possible assertions available. Every test suite has a default set of TestAssertions to use, but these can be overridden. For example, if you are not building a cycle accurate emulator, then you won't want to test the cycles:

var testCases = DAATestSuite.Instance.GetTestCases(DAATestSuite.Instance.DefaultOptions & ~TestAssertions.Cycles);

You will then need unit tests to actually execute the test cases. This should be fairly simple; for example, using NUnit to run the DAA tests is only a few lines of code:

public sealed class DAATests
{
    [TestCaseSource(nameof(TestCases))]
    public void DAA(DAATestCase testCase) => testCase.Execute<MyZ80EmulatorTestHarness>();

    [Pure]
    public static IEnumerable<DAATestCase> TestCases() => DAATestSuite.Instance.GetTestCases();
}

The instruction test suites are:

Program Test Suites

Program test suites run a full Z80 program and check for a test pass/fail message at the end. The programs are tweaked to allow running of just a single test at a time; the originals usually force you to run several tests, which can be slow. They are also tweaked to intercept methods to print results and finish execution.

The program tests work by running a series of instructions and then hashing the values of output registers and flags afterwards. A test then passes if the hash matches the expected hash built into the program. This means they can be challenging to work with; when a test case fails, all you just get a failure message and a mismatched hash. There is no information available about exactly which register or flag was incorrect. They also need a minimum set of instructions to be working as they are full programs. When developing an emulator, it will be much easier to start with the instruction level tests. They are still useful, as they cover cases not covered by the instruction test suites because they execute multiple instructions in a row. For example, I found a bug in OakCpu where certain instructions would break following instructions. They are also quite good to use for benchmarking when trying to improve performance.

Again, running the tests from a unit test framework is straightforward:

public sealed class ZEXALLTests
{
    [TestCaseSource(nameof(TestCases))]
    public void ZEXALL(ZEXALLTestCase testCase) => testCase.Execute<MyZ80EmulatorTestHarness>(TestContext.Progress);

    [Pure]
    public static IEnumerable<ZEXALLTestCase> TestCases() => ZEXALLTestSuite.ZEXALL.TestCases;
}

Note that the TestCase.Execute Method method takes an optional TextWriter which can be used to display the full output of the program in your test output.

The program test suites are:

Last modified: 13 July 2025