{"id":20396861,"url":"https://github.com/asaiyusuke/6502_test_executor","last_synced_at":"2025-04-12T12:51:09.531Z","repository":{"id":43477485,"uuid":"464585208","full_name":"AsaiYusuke/6502_test_executor","owner":"AsaiYusuke","description":"A cross-platform unit testing tool for MOS 6502 assembly","archived":false,"fork":false,"pushed_at":"2025-04-08T13:45:18.000Z","size":663,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-08T14:35:24.263Z","etag":null,"topics":["6502","6502-emulation","assembly","assembly-6502","coverage","coveralls","cross-platform","json-schema","lcov","nes-dev","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AsaiYusuke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-28T17:46:29.000Z","updated_at":"2025-04-08T13:45:18.000Z","dependencies_parsed_at":"2023-02-19T06:16:07.319Z","dependency_job_id":"e01a3123-8959-41b9-b3a7-42eb4328692e","html_url":"https://github.com/AsaiYusuke/6502_test_executor","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsaiYusuke%2F6502_test_executor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsaiYusuke%2F6502_test_executor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsaiYusuke%2F6502_test_executor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsaiYusuke%2F6502_test_executor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AsaiYusuke","download_url":"https://codeload.github.com/AsaiYusuke/6502_test_executor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571346,"owners_count":21126516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["6502","6502-emulation","assembly","assembly-6502","coverage","coveralls","cross-platform","json-schema","lcov","nes-dev","unit-testing"],"created_at":"2024-11-15T04:10:04.439Z","updated_at":"2025-04-12T12:51:09.524Z","avatar_url":"https://github.com/AsaiYusuke.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 6502 Unit Test executor\n\n[![example workflow](https://github.com/AsaiYusuke/6502_test_executor/actions/workflows/make.yml/badge.svg)](https://github.com/AsaiYusuke/6502_test_executor/actions/workflows/make.yml)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/4c943cf3172642469b3249fbc6f4c672)](https://www.codacy.com/gh/AsaiYusuke/6502_test_executor/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=AsaiYusuke/6502_test_executor\u0026amp;utm_campaign=Badge_Grade)\n[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/ellisonleao/magictools#engines-and-frameworks)\n\n![6502 unit test](6502-unit-test.svg)\n\nThis tool enables [unit testing](https://en.wikipedia.org/wiki/Unit_testing) for [MOS Technology 6502](https://en.wikipedia.org/wiki/MOS_Technology_6502) assembly programs across multiple platforms.\n\n## Table of Contents\n\n- [Basic Design](#basic-design)\n- [Supported Testing Features](#supported-testing-features)\n  - [Testable Program](#testable-program)\n  - [Conditions](#conditions)\n  - [Assertions](#assertions)\n  - [Coverage](#coverage)\n  - [Test Classification](#test-classification)\n  - [Additional Useful Features](#additional-useful-features)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Install](#install)\n  - [Running Examples](#running-examples)\n    - [Unit Testing](#unit-testing)\n    - [Coverage File](#coverage-file)\n- [Usage](#usage)\n  - [Building a CA65 Project with Debug Option](#building-a-ca65-project-with-debug-option)\n  - [Creating Unit Tests](#creating-unit-tests)\n  - [Running Tests](#running-tests)\n- [Test Scenario Examples](#test-scenario-examples)\n- [Dependencies](#dependencies)\n- [License](#license)\n\n## Basic Design\n\nThe 6502 Unit Test Executor is designed to facilitate unit testing of 6502 assembly programs.\nIt allows developers to write and execute tests to verify the correctness of their assembly code.\n\n### *Execute Tests on Built-In Emulator*\n\n- The built-in [6502 emulation by Gianluca Ghettini](https://github.com/gianlucag/mos6502) enables stand-alone testing on platforms such as Linux.\n- There's no need to add hooks to the product code to invoke tests.\n\n### *Write Tests with JSON Schema*\n\n- The tool provides [JSON Schema](https://json-schema.org/) document that simplifies test creation.\n\n### *Evaluate Tests like Modern Frameworks*\n\n- It includes many useful evaluation methods found in [the modern UNIT testing frameworks](https://en.wikipedia.org/wiki/List_of_unit_testing_frameworks).\n\n## Supported Testing Features\n\n### Testable Program\n\nSupports testing of some of 6502 assembly instructions.\n\n- Test targets\n  - JSR procedure\n  - NMI procedure\n  - IRQ procedure\n  - Address range\n- Type of interrupts that can occur during testing\n  - NMI\n  - IRQ\n- Mockable call instructions that set the results in registers and memory\n  - JSR\n  - JMP\n\n### Conditions\n\n- Setting up device conditions before testing\n\n  | | Register | Memory | Stack |\n  | :---------------------- | :----------------: | :----------------: | :----------------: |\n  | Set value | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n  | Mock read value history | | :heavy_check_mark: | |\n\n- Evaluating device conditions after testing\n\n  | | Register | Memory | Stack |\n  | :------------------------ | :----------------: | :----------------: | :----------------: |\n  | Check value | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |\n  | Check read/write count | :heavy_check_mark: | :heavy_check_mark: | |\n  | Check write value history | | :heavy_check_mark: | |\n\n- Evaluating processor information\n  - Cycle count\n\n### Assertions\n\n- Assertion operators that determine how tests are evaluated\n  - *\"eq\"* (Equal to)\n  - *\"ne\"* (Not equal to)\n  - *\"gt\"* (Greater than)\n  - *\"ge\"* (Greater than or equal to)\n  - *\"lt\"* (Less than)\n  - *\"le\"* (Less than or equal to)\n  - *\"anyOf\"* (Any of)\n    - Representing logical OR operator\n  - Composite operators\n    - Same as logical AND operator. e.g. \"*gt*\"+\"*lt*\" for range selection\n- Error handling\n  - Write access to readonly memory\n    - Able to detect write operations to readonly memory.\n  - Read access from uninitialized memory\n    - Able to detect read operations from memory that has never had a write operation.\n  - Access to undefined memory\n    - Able to detect memory operations using addresses outside the segment defined at build time.\n  - Access to unauthorized memory\n    - Able to detect access outside the memory for which authorized area has been defined.\n  - Illegal instruction\n    - Able to detect illegal instruction code execution.\n\n### Coverage\n\n- Testable coverage\n  - [LCOV](https://github.com/linux-test-project/lcov) format\n\n### Test Classification\n\n- Aggregated Testing\n  - Group related tests for collective execution.\n- Common configuration settings\n  - Override project-wide configuration settings as needed.\n- Grouping of individual tests\n  - Organize tests into logical groups.\n\n### Additional Useful Features\n\n- When a test terminates with an error, its callback trace can be output.\n- Test evaluations can be executed at any memory address.\n- Test ROM images are detected from debug information file.\n\n## Getting Started\n\n### Prerequisites\n\nEnsure you have a compatible development environment based on [CC65](https://cc65.github.io/) for building and testing 6502 assembly programs.\n\nThe easiest way to install `CC65` on [Ubuntu](https://ubuntu.com/) linux is by running:\n\n```console\n# sudo apt-get install cc65\n```\n\nVerified `CA65` version:\n\n```console\n# ca65 --version\nca65 V2.18 - Ubuntu 2.19-1\n```\n\n### Install\n\nSince this tool repository includes submodules, you must specify the `--recurse-submodules` option when cloning:\n\n```console\n# git clone --recurse-submodules https://github.com/AsaiYusuke/6502_test_executor.git\n# cd 6502_test_executor\n# make\n# ./6502_tester --help\n```\n\n### Running Examples\n\n#### Unit Testing\n\nThe [simple example project](https://github.com/AsaiYusuke/6502_test_executor/tree/master/example) includes many test cases that demonstrate the features:\n\n```console\n# cd example\n# make\nmkdir -p build\nca65 --cpu 6502 --target nes --debug-info -o build/example.o src/example.asm\nmkdir -p dist\nld65  -o dist/example.nes --dbgfile dist/example.dbg --config cfg/nes.cfg --obj build/example.o\nrm coverage/lcov.info\n../6502_tester --debug=dist/example.dbg --coverage=coverage/lcov.info --segment=\"CODE\" --quiet-summary --quiet-ok -t test/ok/customize.configurations.test.json\n../6502_tester --debug=dist/example.dbg --coverage=coverage/lcov.info --segment=\"CODE\" --quiet-summary --quiet-ok -t test/ok/definitions.test.json\n../6502_tester --debug=dist/example.dbg --coverage=coverage/lcov.info --segment=\"CODE\" --quiet-summary --quiet-ok -t test/ok/error.timeout.test.json\n:\nAll tests passed.\n```\n\n#### Coverage File\n\nWhen the project is built, the coverage file is saved in the [example/coverage/lcov.info](example/coverage/lcov.info) in the case of the example project.\n\nThe coverage file can be used to integrate with tools like [Coveralls GitHub Action](https://github.com/marketplace/actions/coveralls-github-action), and more.\n\nThe results of the example project can be seen on [Coveralls](https://coveralls.io/github/AsaiYusuke/6502_test_executor).\\\n[![Coverage Status](https://coveralls.io/repos/github/AsaiYusuke/6502_test_executor/badge.svg?branch=master)](https://coveralls.io/github/AsaiYusuke/6502_test_executor?branch=master)\n\n## Usage\n\n```mermaid\nflowchart LR;\n  A(Assembly program);\n  C[[CA65]];\n  B(Binary);\n  D(Debug information);\n  V[[Visual Studio Code]];\n  S(Test scenario);\n  U[[6502 Unit Test executor]];\n  R[(Test result)];\n  L[(Test coverage)];\n\n  subgraph Build CA65 project\n    A --\u003e C --\u003e B \u0026 D;\n  end\n\n  subgraph Create unit test\n    V -- Json schema --\u003e S;\n  end\n\n  subgraph Run test\n    B \u0026 D \u0026 S --\u003e U --\u003e R \u0026 L;\n  end\n```\n\n### Building a CA65 Project with Debug Option\n\nBuild your 6502 project using the [CA65 assembler](https://cc65.github.io/doc/ca65.html) and [LD65 linker](https://cc65.github.io/doc/ld65.html) with *debug information generation* enabled.\n\n### Creating Unit Tests\n\nCreate test scenario files containing three key items in JSON format:\n\n- *Test target*\n\n  The starting address of the test procedure\n\n- *Setup condition*\n\n  The settings of the registers and memory before the test\n\n- *Expected condition*\n\n  The expected responses of the registers and memory after the test\n\n#### JSON Schema File\n\nThe tool also provides a [JSON Schema](https://json-schema.org/) document that simplifies creating test scenario files.\n\nIf you use [Visual Studio Code](https://code.visualstudio.com/), it will provide formatting error notifications and auto-completion based on JSON Schema.\n\n### Running Tests\n\nRun the tool with the prepared debug information file and test scenario file:\n\n```text\n6502_tester -d \u003cdebug information\u003e -t \u003ctest scenario\u003e\n```\n\nTest coverage can also be measured.\nBoth the coverage file and the segment names used in the debug information file must be specified to enable coverage reporting.\n\n```text\n6502_tester -d \u003cdebug information\u003e -t \u003ctest scenario\u003e -c \u003ccoverage\u003e -s \u003csegment names\u003e\n```\n\nYou can find all command-line arguments in the help:\n\n```console\n# ./6502_tester --help\n  ./6502_tester {OPTIONS}\n\n    6502 test executor\n\n  OPTIONS:\n\n      -h, --help                        Show this help menu.\n      -d[DEBUG], --debug=[DEBUG]        Specify the path of the debug\n                                        information file used for testing.\n      -t[TEST], --test=[TEST]           (REQUIRED)\n                                        Specify the path of the test scenario\n                                        file.\n      -c[COVERAGE],\n      --coverage=[COVERAGE]             Specify the path of the coverage file.\n      -s[SEGMENT], --segment=[SEGMENT]  Specify the segment names for coverage.\n      -i[ID], --id=[ID]                 Specify the test ID.\n      --timeout=[TIMEOUT]               Specify the timeout period before the\n                                        test becomes an error.\n      -q, --quiet                       Do not show any output.\n      --quiet-ok                        Do not show the successful output.\n      --quiet-fail                      Do not show the failed output.\n      --quiet-summary                   Do not show the test summary output.\n\n```\n\n### Note\n\nSome options can be specified either as command-line arguments or test scenario file ([See example](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/customize.configurations.test.json)).  \nIf both are specified, the values in the test scenario file take precedence.\n\n## Test Scenario Examples\n\n### Register Condition examples\n\n- [Check value of A/X/Y registers](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/register/register.axy.value.test.json)\n- [Check read/write count of A/X/Y registers](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/register/register.axy.count.test.json)\n- [Check value of Processor status register flags](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/register/register.status.flag.value.test.json)\n- [Check read/write count of Processor status register flags](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/register/register.status.flag.count.test.json)\n- [Check machine when PC register arrives at a specific address](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/register/init.code.test.json)\n\n### Memory Condition examples\n\n- [Memory addressing](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/memory/memory.addressing.test.json)\n- [Check value of memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/memory/memory.value.check.test.json)\n- [Check read/write count of memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/memory/memory.count.check.test.json)\n- [Batch selection of continuous memory area](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/memory/memory.contiguous.memory.area.test.json)\n- [Sequential change value](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/memory/memory.sequential.change.value.test.json)\n\n### Stack Condition examples\n\n- [Check value of stack](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/stack/stack.value.check.test.json)\n- [rts to caller](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/stack/stack.rts.check.test.json)\n\n### Processor Condition examples\n\n- [Cycle count information](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/processor/error.timeout.test.json)\n- [Interrupt hooks](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/processor/interrupt.test.json)\n- [Call mocked proc](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/processor/mock.proc.test.json)\n\n### Testable Procedure examples\n\n- [JSR proc](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/test_type/jsr.test.json)\n- [NMI proc](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/test_type/nmi.test.json)\n- [IRQ proc](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/test_type/irq.test.json)\n- [Address range](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/test_type/address.test.json)\n\n### Error Handling examples\n\n- [Write access to readonly memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/error.readonly.test.json)\n- [Read access from uninitialized memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/error.uninitialized_memory_read.test.json)\n- [Access to undefined memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/error.out_of_segment.test.json)\n- [Access to unauthorized memory](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/error.unauthorized_memory_access.test.json)\n- [Illegal instruction](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/error.illegal_instruction.test.json)\n\n### Test Classification examples\n\n- [Aggregated testing](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/classification/project.test.json)\n- [Common configuration settings](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/fail/200/classification/error.out_of_segment.test.json)\n  - [Override from project-wide configuration settings](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/classification/merge_config.test.json)\n- [Grouping of individual tests](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/classification/group.test.json)\n\n### Misc examples\n\n- [Customize configurations](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/misc/customize.configurations.test.json)\n- [Skip test (ignore)](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/misc/skip.test.json)\n- [Complex evaluation](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/misc/evaluation.test.json)\n- [Definitions](https://github.com/AsaiYusuke/6502_test_executor/blob/master/example/test/ok/misc/definitions.test.json)\n\n## Dependencies\n\nThis project uses the following libraries:\n\n- [Gianluca Ghettini's 6502 emulator](https://github.com/gianlucag/mos6502)\n  - [Erik Lothe's 6502 Unit test executor](https://github.com/89erik/6502_test_executor)\n- [Taylor C. Richberger's args](https://github.com/Taywee/args)\n- [Niels Lohmann's JSON for Modern C++](https://github.com/nlohmann/json)\n\n## License\n\nThis project is available under the **MIT license**. See the [LICENSE](LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasaiyusuke%2F6502_test_executor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasaiyusuke%2F6502_test_executor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasaiyusuke%2F6502_test_executor/lists"}