Developer Guide

This document is intended for SuperKernel project developers, explaining how to write and maintain System Test (ST) cases and related resources.

Document Positioning

README.md: For general users, focusing on environment preparation, compilation, and basic verification.
docs/developer_guide.md (this document): For contributors, covering testing framework, dependency management, and debugging techniques.

Directory Structure Overview

super_kernel/
  src/
    superkernel/    # core business code
  tests/
    fixtures/     # runtime environment configuration, sub-kernel compilation and other fixtures
    ut/             # unit tests
    st/
      data/         # golden data samples
      scenarios/    # end-to-end test scripts
    utils/          # common validation and utility functions
    generated/      # temporary artifacts generated during test execution (not included in version control)
  docs/             # project documentation
  examples/         # samples or demonstration scripts
  scripts/          # auxiliary scripts (such as packaging, debugging tools)
  coverage/         # coverage output directory (generated after testing)

Fixed Fixtures

tmp_dir (located in fixtures/config.py): Provides independent tests/generated/<timestamp>_<pid> directory for each test session and cleans up after test completion.
data_dir (located in fixtures/config.py): Locates to tests/st/data/, facilitating scenario reading of golden files or configurations.
soc_version (located in fixtures/config.py): Specifies default SoC information, currently defaults to Ascend910B1; if other versions are needed, override within scenarios or add new fixtures.
subkernel compilation fixtures (located in fixtures/sub_kernel.py): Include subkernel_is_inf_default, subkernel_is_inf_split_mode1, subkernel_is_finite_default, and so on. Test cases can use indirect fixtures like subkernel_inf / subkernel_finite to combine different configurations.

When developers add new fixtures, please keep scope, resource release strategy consistent with existing implementations.

ST Scenario Writing Conventions

Test scripts are stored in st/scenarios/, files must be named test_*.py, and add @pytest.mark.st marker on functions.
All scenarios should use existing fixtures through dependency injection (such as tmp_dir, data_dir), avoid manually creating temporary directories.
Generated codegen, logs, and other artifacts are by default located under tmp_dir/<scenario>/kernel_meta/, naming conventions:
- C++ source files: <kernel_name>_<pid>_kernel.cpp
- Compilation logs: <kernel_name>_<pid>.log

Golden Data and Validation

Golden files (such as C++ code, JSON) are stored under tests/st/data/<scenario>/, explicitly referenced by use cases.
st/utils/validators.py provides common validation functions:
- validate_codegen_output(kernel_root, kernel_name, expected_source): Compares generated C++ with golden file for consistency.
- validate_compile_options(kernel_root, kernel_name, expected_options): Locates Bisheng compilation command in corresponding log, confirms inclusion of specified options.
When adding validation logic, suggest encapsulating into independent functions for reuse by multiple scenarios.

Dependency Management Process

pyproject.toml is the single source of dependency information: [project.dependencies] for runtime dependencies, [project.optional-dependencies.dev] lists development/testing tools.
requirements-dev.txt is locked result, generated by pip-compile based on pyproject.toml, for scenarios requiring completely reproducible environments (such as CI). Update method:
```
cd super_kernel
pip install pip-tools         # install pip-tools
pip-compile --extra dev pyproject.toml --output-file requirements-dev.txt
```
After execution, same-name files will be overwritten, please commit latest results to version control.

Running and Debugging

Basic Process

Follow project root directory "README" to complete Ascend toolchain and Python environment initialization.
In virtual environment, install project in editable mode, with dev extra for testing tools:
```
cd super_kernel
pip install -e .[dev]
```
Continue executing subsequent commands in the same terminal session.
Run unit tests (UT):
```
pytest tests/ut -m ut
```
Run System Test suite:
```
pytest tests/st -m st
```
After run completion, if need to preserve artifacts in tests/generated/, add --keep-generated parameter when executing pytest.

Enabling Coverage

Support coverage statistics for UT, ST or combined tests. Command examples:

UT Coverage Only:

pytest tests/ut -m ut \
  --cov=superkernel \
  --cov-report=term-missing \
  --cov-report=html \
  --cov-report=xml

ST Coverage Only:

pytest tests/st -m st \
  --cov=superkernel \
  --cov-report=term-missing \
  --cov-report=html \
  --cov-report=xml

UT + ST Comprehensive Coverage:

pytest \
  --cov=superkernel \
  --cov-report=term-missing \
  --cov-report=html \
  --cov-report=xml

After execution, coverage files are generated:

Terminal Report: Coverage statistics and uncovered line numbers printed in command line.
HTML Report: super_kernel/coverage/html/index.html.
XML Report: super_kernel/coverage/coverage.xml.
Raw Data File: super_kernel/coverage/.coverage.

Coverage related configuration is concentrated in [tool.coverage.*] section of pyproject.toml.

File Management Principles

Version Control Ignore Strategy

Project uses root directory unified management .gitignore strategy, subdirectories without exception do not separately set .gitignore: avoid rule dispersion, facilitate unified maintenance.

Temporary File Management

Temporary files generated by testing are stored in tests/generated/ directory.
Coverage report files are stored in project root directory coverage directory.

Contribution Suggestions

Read project root directory "CONTRIBUTING.md", which contains project contribution guidelines. Meanwhile, within the contribution guide, you can jump to basic preparation actions for participating in all CANN open source projects, including but not limited to code download, submission, pipeline triggering, code review processes. Ensure all necessary preparation work is completed before participating in contribution.
Before submission, please run pytest to confirm all test cases pass.
Recommend running coverage tests before submission to ensure new code has appropriate test coverage.
When adding fixtures or tools, supplement necessary documentation and comments, keep directory structure clear.
Golden file updates require caution, recommend explaining difference sources in review first.

If more complex debugging needs exist, can continue expanding chapters or supplementing FAQ on this guide basis.