Metadata-Version: 2.4
Name: yini-test-suite
Version: 0.3.0rc1
Summary: Shared test harness and case corpus for YINI parser implementations.
Author: Marko K. Seppänen
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/YINI-lang/yini-test-suite
Project-URL: Repository, https://github.com/YINI-lang/yini-test-suite
Project-URL: Issues, https://github.com/YINI-lang/yini-test-suite/issues
Project-URL: Changelog, https://github.com/YINI-lang/yini-test-suite/blob/main/CHANGELOG.md
Keywords: yini,testing,parser,conformance,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# yini-test-suite

`yini-test-suite` is the shared command-line test runner and case corpus for
YINI parser implementations.

It does not parse YINI itself. Instead, it calls a parser implementation through
an adapter, compares the parser output with the expected JSON for each case, and
reports pass/fail results consistently.

The goal is to give different YINI parsers the same conformance target.

## 📦 Install

Requires Python 3.10 or newer.

```bash
python -m pip install yini-test-suite
```

Check that the CLI is available:

```bash
yini-test-suite --help
```

The package includes the shared smoke and golden case corpus, so normal installed
usage does not require a separate `--cases-root` path.

## 🚀 Basic Usage

Run the smoke suite against a parser adapter:

```bash
yini-test-suite smoke --adapter python path/to/adapter.py --input "{input}" --mode "{mode}"
```

Run all bundled cases in both lenient and strict mode:

```bash
yini-test-suite all --all-modes --adapter python path/to/adapter.py --input "{input}" --mode "{mode}"
```

Important: `--adapter` must be the last `yini-test-suite` option. Everything
after `--adapter` is treated as part of the adapter command.

The runner replaces:
- `{input}` with the current `.yini` case path.
- `{mode}` with `lenient` or `strict`.

Use `--show-progress` if you also want a `RUN` line before each case:

```bash
yini-test-suite all --all-modes --show-progress --adapter python path/to/adapter.py --input "{input}" --mode "{mode}"
```

The double quotes around the placeholders make these commands work in Bash,
PowerShell, and Windows Command Prompt.

## 🧪 Suites and modes

Suites:
- `smoke` runs a smaller confidence suite.
- `golden` runs the broader fixed-output conformance suite.
- `all` runs both `smoke` and `golden`.

Modes:
- Lenient mode is the default.
- `--strict` runs strict-mode cases.
- `--all-modes` runs both lenient and strict mode and prints one combined summary.

## 🔌 Adapter Contract

An adapter is a small command-line program owned by a parser implementation. It
accepts an input file and parser mode, then prints parsed JSON to `stdout` on
success or diagnostics to `stderr` on failure.

The expected shape is:

```bash
adapter --input <path-to-yini-file> --mode <lenient|strict>
```

For details, see [docs/adapter-contract.md](./docs/adapter-contract.md).

## Official Ecosystem Examples

Parser-specific adapter scripts are maintained in their parser repositories, not
in this runner package.

However, this project provides official adapter integrations for
[`yini-parser-typescript`](https://github.com/YINI-lang/yini-parser-typescript)
and [`yini-parser-python`](https://github.com/YINI-lang/yini-parser-python)
through ready-made command examples and Taskfile tasks. They are included to
show working examples and because those parsers are part of the official YINI
ecosystem.

The expected sibling repository layout for those examples is:

```text
YINI-lang-WORK/
  yini-test-suite/
  yini-parser-typescript/
  yini-parser-python/
```

Example TypeScript adapter command:

```bash
yini-test-suite all --all-modes --adapter node ../yini-parser-typescript/dist-tools/tools/yini-test-adapter.js --input "{input}" --mode "{mode}"
```

Example Python adapter command:

```bash
yini-test-suite all --all-modes --adapter python ../yini-parser-python/tools/yini_parser_adapter.py --input "{input}" --mode "{mode}"
```

When working from the source repository, the matching Taskfile commands are:

```bash
task run-all-typescript
task run-all-python
```

If these runs expose parser or adapter problems, fix those issues in the
corresponding parser repository unless the shared case corpus or runner contract
is wrong.

## Output

A run starts with the runner name and version:

```text
yini-test-suite 0.3.0rc1
```

Each case is reported as `PASS` or `FAIL`, followed by a final summary:

```text
YINI Test Suite Summary
yini-test-suite: 0.3.0rc1
Adapter: yini-parser-typescript
Parser version: 1.6.1
YINI spec: 1.0.0 RC 6
Test suite: "all"
```

For valid cases, the runner compares the adapter JSON output with the matching
expected `.json` file. Warning cases also check expected warning diagnostics.
Invalid cases are expected to fail.

## What This Package Does Not Do

- It does not contain a YINI parser.
- It does not define parser-specific parsing behavior.
- It does not make parser-specific adapters part of the public `yini-test-suite`
  Python API.

## 🛠️ Development

For source checkout setup, Taskfile commands, local adapter runs, build checks,
and troubleshooting, see [docs/Development-Setup.md](./docs/Development-Setup.md).

Useful maintainer references:
- [docs/case-contract.md](./docs/case-contract.md)
- [docs/adapter-contract.md](./docs/adapter-contract.md)
- [docs/runner-flow.md](./docs/runner-flow.md)
- [docs/Maintainer-Doc.md](./docs/Maintainer-Doc.md)

## 💬 Help, feedback, and issues

For bugs, feedback, or other issues with `yini-test-suite`,
[open an issue](https://github.com/YINI-lang/yini-test-suite/issues).

For general YINI information, see:
- [YINI homepage](https://yini-lang.org?utm_source=github&utm_medium=referral&utm_campaign=yini_test&utm_content=readme_project_links)
- [YINI GitHub organization](https://github.com/YINI-lang)
- [`yini-test-suite` repository](https://github.com/YINI-lang/yini-test-suite)

## About YINI

YINI is a human-readable, INI-inspired, indentation-insensitive configuration
format with clear nested sections, explicit structure, and predictable parsing.

[yini-lang.org](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_test&utm_content=readme_footer) |
[YINI-lang on GitHub](https://github.com/YINI-lang)
