M6502

Test suites for MOS Technology 6502 emulators.

Getting Started

Start by installing the NuGet package into your test project:

dotnet add package MrKWatkins.EmulatorTestSuites.M6502

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

Harness Requirements

Your M6502TestHarness implementation needs to expose the machine state that the tests validate:

• registers A, X, Y, S, P, and PC;
• byte-level memory reads and writes;
• execution of a single instruction; and
• a test-framework specific failure mechanism via AssertFail.

The shared base class already provides:

• TStates for total cycles taken by the instruction;
• helpers such as ReadWordFromMemory, WriteWordToMemory, CopyToMemory, and ClearMemory;
• assertion batching through CreateAssertionScope; and
• cycle recording infrastructure through RecordCycles, Cycles, and MutableCycles.

When RecordCycles is enabled, your harness should append Cycle instances to MutableCycles in the order they occur and keep TStates in sync with the instruction that just ran.

Some 6502 program suites can also run steppable emulators in true step-by-step mode. To opt into that, derive your harness from M6502SteppableTestHarness and implement Step(), returning true when the step was an opcode fetch.

Test Suite Types

The 6502 test suites fall into two families: instruction and program.

Instruction Test Suites

Instruction test suites execute one instruction at a time and compare the resulting processor state, memory, and recorded bus activity.

Running the tests from a unit test framework should be straightforward; for example, using NUnit with the Single Step suite:

public sealed class SingleStepTests
{
    [TestCaseSource(nameof(TestCases))]
    public void SingleStep(SingleStepTestCase testCase) => testCase.Execute<MyM6502EmulatorTestHarness>();

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

The currently available instruction test suites are:

• Single Step

Program Test Suites

Program test suites load and execute a complete 6502 program, then detect success or failure at the program level rather than after a single instruction.

These suites are useful once your emulator is capable of running longer instruction sequences correctly. They also validate that state carries cleanly from one instruction to the next, which can catch bugs that isolated instruction tests miss.

Running them from a unit test framework is also straightforward; for example, using NUnit with the Klaus Dormann suite:

public sealed class KlausDormannTests
{
    [TestCaseSource(nameof(TestCases))]
    public void Test(KlausDormannTestCase testCase) => testCase.Execute<MyM6502EmulatorTestHarness>(TestContext.Progress);

    [Pure]
    public static IEnumerable<KlausDormannTestCase> TestCases() => KlausDormannTestSuite.Instance.TestCases;
}

The currently available program test suites are:

• Klaus Dormann