Metadata-Version: 2.4
Name: yini-test-suite
Version: 0.3.0b1
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

The **yini-test-suite** tool is the shared case corpus (test harness) for YINI parser implementations.

It does not contain a YINI parser itself. Instead, it invokes a chosen parser implementation through an adapter, compares the actual output with the expected output, and reports pass/fail results consistently.

The goal of `yini-test-suite` is to stay implementation-agnostic, so that multiple YINI parsers can be tested in a uniform way.

---

## What `yini-test-suite` does

- Runs a chosen parser implementation through an adapter.
- Compares actual output with expected output.
- Reports pass/fail results consistently.
- Provides a shared test corpus for multiple YINI parser implementations.

---

## What `yini-test-suite` does not do

- It does not contain a YINI parser.
- It does not contain parser-specific execution logic.
- It does not own parser-specific adapters.

---

## Quick Start

### First-time setup

It is assumed you are in the `yini-test-suite/` directory, and that you have the directory `yini-parser-python/` already alongside the directory `yini-test-suite`.

Run:
```bash
task clean
task install
task test
task run-smoke-python-lenient
task run-smoke-python-strict
```

If you want to test the TypeScript parser instead, replace the last command with:
```bash
task run-smoke-typescript-lenient
task run-smoke-typescript-strict
```

### Later runs

Run these commands from the `yini-test-suite/` directory.

Run:
```bash
task run-smoke-python-lenient
task run-smoke-python-strict
```

or:

```bash
task run-smoke-typescript-lenient
task run-smoke-typescript-strict
```

depending on which parser implementation you want to test.

---

## Expected local repository layout

The predefined Taskfile commands assume that the parser repositories are located next to `yini-test-suite`:

```text
/
├─ yini-test-suite/
├─ yini-parser-typescript/
└─ yini-parser-python/
```

Adapter paths are **relative to** this directory: `yini-test-suite/`:
- The TypeScript parser adapter is expected at:  
  `../yini-parser-typescript/dist-tools/tools/yini-test-adapter.js`
- The Python parser adapter is expected at:  
  `../yini-parser-python/tools/yini_parser_adapter.py`

## Installing and running tests

### 1. Clean local cache files

```bash
task clean
```

This removes Python cache files and temporary tool caches.

### 2. Install dependencies

```bash
task install
```

This installs the development dependencies and installs `yini-test-suite` itself **in editable mode**.

### 3. Show available tasks

```bash
task
```

### 4. Test `yini-test-suite` itself

```bash
task test
```

This runs the unit and integration tests for the `yini-test-suite` runner.

A successful result should look similar to:
```txt
34 passed
```

### 5. Run smoke tests against `yini-parser-python`

```bash
task run-smoke-python-lenient
task run-smoke-python-strict
```

This runs the smoke test cases against the Python parser adapter.

The task uses a command similar to:
```bash
python -m yini_test smoke \
  --cases-root src/yini_test/cases \
  --adapter python ../yini-parser-python/tools/yini_parser_adapter.py --input {input} --mode {mode}
```

The `{input}` and `{mode}` placeholders are replaced automatically for each test case.

### 6. Run all Python cases

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

This runs the Python adapter against smoke lenient, smoke strict, golden lenient, and golden strict cases, then prints one combined summary.

The task uses:
```bash
python -m yini_test all --all-modes \
  --cases-root src/yini_test/cases \
  --adapter python ../yini-parser-python/tools/yini_parser_adapter.py --input {input} --mode {mode}
```

### 7. Run all TypeScript cases

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

This runs the TypeScript adapter against smoke lenient, smoke strict, golden lenient, and golden strict cases, then prints one combined summary.

The task uses:
```bash
python -m yini_test all --all-modes \
  --cases-root src/yini_test/cases \
  --adapter node ../yini-parser-typescript/dist-tools/tools/yini-test-adapter.js --input {input} --mode {mode}
```

### 8. Understanding the result

Each case is reported as `PASS` or `FAIL`.

Example:
```txt
PASS  "cases\smoke\lenient\valid\1-minimal.yini"
FAIL  "cases\smoke\lenient\valid\3-nested-sections.yini"
```

Use `--show-progress` to also print a `RUN` line before each case executes.

For valid cases, `yini-test-suite` compares the parser output with the matching expected JSON file.

For example:
```txt
cases/smoke/lenient/valid/3-nested-sections.yini
```

is compared with:
```txt
cases/smoke/lenient/valid/3-nested-sections.json
```

If a test case fails, `yini-test-suite` prints the difference showing the expected output and the actual parser output.

---

## Project structure

- `src/yini_test/__main__.py` is the package entry point.
- `src/yini_test/cli.py` handles the command-line argument parsing.
- `src/yini_test/runner.py` contains the core test-running logic.
- `src/yini_test/cases/` contains the shared parser test case corpus.
- `tests/` contains tests for this `yini-test-suite` project itself.

Current case groups include:
- `golden/` for cases where valid input must produce exact expected output.
- `smoke/` for smaller practical cases used to catch obvious parser issues.

---

## Adapters

This project itself does not include adapters for specific parser implementations.

Instead, each parser project/repository should provide and maintain its own adapter logic for `yini-test-suite` to call.

---

## Related documents
- [docs/adapter-contract.md](./docs/adapter-contract.md)
- [docs/case-contract.md](./docs/case-contract.md)
- [docs/runner-flow.md](./docs/runner-flow.md)

---

**^YINI ≡**  
> YINI is a human-readable, INI-inspired, indentation-insensitive configuration format with clear nested sections, explicit structure, and predictable parsing.
> 
> It has a formal specification and a defined grammar.

[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)  
