diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 000000000..114423782
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,35 @@
+name: Tests
+
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  pytest:
+    strategy:
+      max-parallel: 6
+      matrix:
+        # Same Python matrix shape as the Create Examples workflow so
+        # we get coverage from the oldest officially supported runtime
+        # (3.7) up through the latest released (3.12).
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        include:
+          - os: ubuntu-22.04
+            python-version: "3.7"
+          - os: ubuntu-22.04
+            python-version: "3.8"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Setup Graphviz
+        uses: ts-graphviz/setup-graphviz@v2
+      - name: Install package + test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          pip install pytest
+      - name: Run pytest
+        run: pytest -v
diff --git a/CLAUDE.md b/CLAUDE.md
index a35b20f7a..c3edd06d2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,18 +10,33 @@ This repo is the **upstream Python CLI**. A separate GUI front-end is being buil
 
 ## Commands
 
-WireViz has **no automated test suite**. The de-facto regression check is rebuilding the examples and diffing the output.
+WireViz has both an **automated pytest suite** (`tests/`) and a separate **example-rebuild regression check** (`build_examples.py`). They serve complementary purposes — pytest validates the API and CLI surface; the example sweep validates rendered visual output across the gallery.
 
 ```bash
 # Install for development (from repo root)
 pip install -e .
+pip install pytest
+
+# Run the unit / integration test suite (~134 tests, ~5s)
+pytest
+
+# Run a single test file or test
+pytest tests/test_regressions.py
+pytest tests/test_cli.py::test_cli_template_dir
 
 # Run the CLI on a YAML file (produces .gv .svg .png .html .bom.tsv next to input)
 wireviz path/to/file.yml
 
-# Limit output formats: g=gv h=html p=png s=svg t=tsv
+# Limit output formats: g=gv h=html p=png s=svg t=tsv P=pdf
 wireviz -f hps path/to/file.yml
 
+# Stdin → stdout: pipe YAML in, get one rendered format out
+cat harness.yml | wireviz -f s -O - -    > harness.svg
+cat harness.yml | wireviz -f p -O - -    > harness.png
+
+# .png input: extract the embedded YAML and re-render
+wireviz harness.png
+
 # Rebuild every demo, example, and tutorial (must cd into src/wireviz)
 cd src/wireviz && python build_examples.py
 
@@ -40,7 +55,23 @@ cd src/wireviz && python build_examples.py compare -g examples tutorial demos
 
 GraphViz must be installed as a system dep (`dot -V`). Code is formatted with `black` + `isort` (`isort` profile is `black`, configured in `pyproject.toml`).
 
-CI (`.github/workflows/`) runs only `build_examples.py` across Python 3.7–3.12 — there is no `pytest`. If you add real tests, also wire them into CI.
+CI (`.github/workflows/`) runs both `pytest` (the `Tests` workflow) and `build_examples.py` (the `Create Examples` workflow) across Python 3.7–3.12. Both must pass for a PR to be considered green.
+
+## Test suite layout (`tests/`)
+
+- **`tests/test_smoke.py`** — every output format renders without error, has the right magic bytes, and produces the expected basic structure.
+- **`tests/test_parse.py`** — the `wireviz.parse()` library API: input shapes (Path / str / dict), output shapes, return_types, source_path auto-fill, embed_yaml flag.
+- **`tests/test_cli.py`** — every CLI flag via Click's `CliRunner`. Covers stdin/stdout, `.png` input round-trip, `--no-embed-yaml`, `--template-dir`, `--prepend`, error paths.
+- **`tests/test_harness.py`** — `Harness` public methods, the `_render` dict shape contract, file vs stdout dispatch.
+- **`tests/test_dataclasses.py`** — `Connector` / `Cable` / `Tweak` / `Options` / `Image` coercion and validation logic.
+- **`tests/test_colors.py`** — color schemes (DIN/IEC/T568/TEL), hex parsing, `get_color_hex` padding behavior.
+- **`tests/test_bom.py`** — BOM aggregation: identical-component dedup, ignore_in_bom, additional_bom_items, bundle category, part-number columns.
+- **`tests/test_regressions.py`** — **one test per upstream-PR port + every gemini review fix.** This is where every bug we ported a fix for gets pinned down so it can never silently regress. If you change behavior touched by any of those PRs, expect tests here to fail and update them deliberately.
+- **`tests/test_round_trip.py`** — PNG embed/extract, stdin→stdout pipelines, dict-input no-mutation contract.
+
+`tests/conftest.py` provides shared fixtures (paths to small targeted YAMLs in `tests/fixtures/`). The fixture YAMLs are deliberately separate from the gallery YAMLs in `examples/` so tests aren't coupled to visual gallery changes.
+
+`pyproject.toml` configures pytest to treat unexpected warnings as errors (`filterwarnings = ["error", "ignore::SyntaxWarning"]`) so deprecations like the `re.sub(..., 1)` → `re.sub(..., count=1)` migration get caught early.
 
 ## Architecture
 
diff --git a/pyproject.toml b/pyproject.toml
index 5d7bf33d9..f55d39d67 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,2 +1,15 @@
 [tool.isort]
 profile = "black"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+# Treat unexpected warnings as errors so dataclass / deprecation drift is caught
+filterwarnings = [
+    "error",
+    # graphviz emits a SyntaxWarning on Python 3.12+ for an internal regex —
+    # not our problem and not worth blocking the suite on
+    "ignore::SyntaxWarning",
+]
diff --git a/src/wireviz/Harness.py b/src/wireviz/Harness.py
index 96ea37aa8..751960b9e 100644
--- a/src/wireviz/Harness.py
+++ b/src/wireviz/Harness.py
@@ -172,7 +172,8 @@ def _extend_tweak(self, node: Union[Connector, Cable]) -> None:
                 k, v = rph(k), rph(v)
                 if k in s_dict and v != s_dict[k]:
                     raise ValueError(
-                        f"{node.name}.tweak.override.{ident}.{k} conflicts with another"
+                        f"{node.name}.tweak.override.{ident}.{k}: new value "
+                        f"{v!r} conflicts with existing {s_dict[k]!r}"
                     )
                 s_dict[k] = v
             # Keep the empty dict rather than collapsing to None — the
@@ -935,7 +936,7 @@ def _render(
                 # rendered in this same call; otherwise let the template
                 # fall back to reading {output_dir}/{output_name}.png.
                 png_b64 = (
-                    f"data:image/png;base64, {base64.b64encode(png_bytes).decode('utf-8')}"
+                    f"data:image/png;base64,{base64.b64encode(png_bytes).decode('utf-8')}"
                     if png_bytes is not None
                     else None
                 )
diff --git a/src/wireviz/svgembed.py b/src/wireviz/svgembed.py
index 3e33f631c..37c98b4e9 100644
--- a/src/wireviz/svgembed.py
+++ b/src/wireviz/svgembed.py
@@ -13,7 +13,7 @@ def data_URI_base64(file: Union[str, Path], media: str = "image") -> str:
     """Return Base64-encoded data URI of input file."""
     file = Path(file)
     b64 = base64.b64encode(file.read_bytes()).decode("utf-8")
-    uri = f"data:{media}/{get_mime_subtype(file)};base64, {b64}"
+    uri = f"data:{media}/{get_mime_subtype(file)};base64,{b64}"
     # print(f"data_URI_base64('{file}', '{media}') -> {len(uri)}-character URI")
     if len(uri) > 65535:
         print(
@@ -36,7 +36,7 @@ def replace(match: re.Match) -> str:
             images_b64[imgurl] = base64.b64encode(image).decode("utf-8")
         return image_tag(
             match["PRE"] or "",
-            f"data:image/{get_mime_subtype(imgurl)};base64, {images_b64[imgurl]}",
+            f"data:image/{get_mime_subtype(imgurl)};base64,{images_b64[imgurl]}",
             match["POST"] or "",
         )
 
diff --git a/src/wireviz/wireviz.py b/src/wireviz/wireviz.py
index 82a55aec5..5454b366a 100755
--- a/src/wireviz/wireviz.py
+++ b/src/wireviz/wireviz.py
@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
+import copy
 import platform
 import sys
 from pathlib import Path
-from typing import Any, Dict, List, Tuple, Union
+from typing import Any, Dict, List, Optional, Tuple, Union
 
 import yaml
 
@@ -112,6 +113,10 @@ def parse(
         raise TypeError(
             f"Expected a dict as top-level YAML input, but got: {type(yaml_data)}"
         )
+    # When inp was a Path, derive source_path automatically so callers
+    # don't have to pass it twice. Matches the docstring contract.
+    if source_path is None and yaml_file is not None:
+        source_path = yaml_file
     write_to_stdout = (
         output_formats and (str(output_dir) == "-" or str(output_name) == "-")
     )
@@ -506,8 +511,10 @@ def _get_yaml_data_and_path(
         yaml_data = yaml.safe_load(yaml_str)
     else:
         # received a Dict — serialize back to YAML so the caller has a
-        # text form for round-trip embedding into PNG output.
-        yaml_data = inp
+        # text form for round-trip embedding into PNG output, and
+        # deep-copy so the parsing pipeline's in-place expansion of
+        # the connections section doesn't leak back to the caller.
+        yaml_data = copy.deepcopy(inp)
         yaml_path = None
         yaml_str = yaml.safe_dump(inp, sort_keys=False, allow_unicode=True)
     return yaml_data, yaml_path, yaml_str
diff --git a/src/wireviz/wv_cli.py b/src/wireviz/wv_cli.py
index ebbca72c9..ca1c06e26 100644
--- a/src/wireviz/wv_cli.py
+++ b/src/wireviz/wv_cli.py
@@ -96,7 +96,12 @@ def wireviz(
     --output-dir or --output-name to write a single rendered format to
     stdout (e.g. ``cat harness.yml | wireviz -f s -O - -``).
     """
-    sys.stderr.write(f"\n{APP_NAME} {__version__}\n")
+    # Use ``click.echo(..., err=True)`` instead of ``sys.stderr.write``
+    # for status/log lines so they reach Click's captured-stderr stream
+    # uniformly across Click 8.1 (only captures click.echo) and 8.2+
+    # (captures sys.stderr.write too). The end-state is the same — log
+    # lines on stderr, render output on stdout.
+    click.echo(f"\n{APP_NAME} {__version__}", err=True)
     if version:
         return  # print version number only and exit
 
@@ -116,7 +121,7 @@ def wireviz(
             if fmt not in output_formats:
                 output_formats.append(fmt)
         else:
-            raise Exception(f"Unknown output format: {code}")
+            raise click.UsageError(f"Unknown output format: {code}")
     output_formats = tuple(output_formats)
     output_formats_str = (
         f'[{"|".join(output_formats)}]'
@@ -136,8 +141,10 @@ def wireviz(
         for prepend_file in prepend:
             prepend_file = Path(prepend_file)
             if not prepend_file.exists():
-                raise Exception(f"File does not exist:\n{prepend_file}")
-            sys.stderr.write(f"Prepend file: {prepend_file}\n")
+                raise click.UsageError(
+                    f"Prepend file does not exist: {prepend_file}"
+                )
+            click.echo(f"Prepend file: {prepend_file}", err=True)
 
             prepend_input += file_read_text(prepend_file) + "\n"
     else:
@@ -150,14 +157,18 @@ def wireviz(
     for file in filepaths:
         if str(file) == "-":
             yaml_input = prepend_input + sys.stdin.read()
-            image_paths = set()
-            sys.stderr.write("Input:        <stdin>\n")
+            # No source-file directory available, so any relative
+            # `image: src:` paths in the stdin YAML are resolved against
+            # the current working directory (matching how a typical
+            # piped invocation would be run from a project root).
+            image_paths = {Path.cwd()}
+            click.echo("Input:        <stdin>", err=True)
             _output_dir = output_dir if output_dir else "-"
             _output_name = output_name if output_name else "stdin"
         else:
             file = Path(file)
             if not file.exists():
-                raise Exception(f"File does not exist:\n{file}")
+                raise click.UsageError(f"Input file does not exist: {file}")
 
             if file.suffix.lower() == ".png":
                 # PNG input: try to recover the YAML embedded by an
@@ -176,10 +187,10 @@ def wireviz(
                         f"'wireviz:yaml' iTXt chunk found)."
                     )
                 yaml_input = prepend_input + embedded
-                sys.stderr.write(f"Input file:   {file} (extracted YAML)\n")
+                click.echo(f"Input file:   {file} (extracted YAML)", err=True)
             else:
                 yaml_input = prepend_input + file_read_text(file)
-                sys.stderr.write(f"Input file:   {file}\n")
+                click.echo(f"Input file:   {file}", err=True)
             image_paths = {file.parent}
             _output_dir = output_dir if output_dir else file.parent
             _output_name = output_name if output_name else file.stem
@@ -188,10 +199,13 @@ def wireviz(
             image_paths.add(Path(p).parent)
 
         if write_to_stdout:
-            sys.stderr.write(f"Output:       <stdout>.{output_formats_str}\n")
+            click.echo(
+                f"Output:       <stdout>.{output_formats_str}", err=True
+            )
         else:
-            sys.stderr.write(
-                f"Output file:  {Path(_output_dir) / _output_name}.{output_formats_str}\n"
+            click.echo(
+                f"Output file:  {Path(_output_dir) / _output_name}.{output_formats_str}",
+                err=True,
             )
 
         wv.parse(
@@ -205,7 +219,7 @@ def wireviz(
             embed_yaml=embed_yaml,
         )
 
-    sys.stderr.write("\n")
+    click.echo("", err=True)
 
 
 if __name__ == "__main__":
diff --git a/src/wireviz/wv_html.py b/src/wireviz/wv_html.py
index 2393317db..71230f433 100644
--- a/src/wireviz/wv_html.py
+++ b/src/wireviz/wv_html.py
@@ -73,7 +73,7 @@ def svgdata() -> str:
             "^<[?]xml [^?>]*[?]>[^<]*<!DOCTYPE [^>]*>",
             "<!-- XML and DOCTYPE declarations from SVG file removed -->",
             svg_input or "",
-            1,
+            count=1,
         )
 
     # generate BOM table
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 000000000..c7cb28147
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+"""Shared pytest fixtures for the WireViz test suite.
+
+Most fixtures yield Path objects pointing at small targeted YAML files
+under ``tests/fixtures/``. These fixtures are intentionally separate
+from the larger gallery YAMLs in ``examples/`` so test failures are
+about the *thing being tested*, not about an unrelated example feature
+shifting underneath us.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+# Ensure the in-tree src/wireviz package is importable when running
+# pytest from the repo root without a prior `pip install -e .`.
+SRC = Path(__file__).resolve().parent.parent / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+@pytest.fixture
+def fixtures_dir() -> Path:
+    return FIXTURES
+
+
+@pytest.fixture
+def minimal_yaml(fixtures_dir: Path) -> Path:
+    """Two-pin connector + 2-wire cable. The smallest renderable harness."""
+    return fixtures_dir / "minimal.yml"
+
+
+@pytest.fixture
+def loopback_yaml(fixtures_dir: Path) -> Path:
+    """Single connector with a ``loops:`` entry, no cables — exercises
+    the auto-instantiation path added by upstream PR #496."""
+    return fixtures_dir / "loopback.yml"
+
+
+@pytest.fixture
+def loopback_template_yaml(fixtures_dir: Path) -> Path:
+    """Connector template with ``loops:`` used via Template.Designator
+    syntax — exercises the auto-instantiation skip added by the
+    review fix on PR #1."""
+    return fixtures_dir / "loopback_template.yml"
+
+
+@pytest.fixture
+def revisions_yaml(fixtures_dir: Path) -> Path:
+    """metadata.revisions with three entries — exercises the
+    %revision% placeholder."""
+    return fixtures_dir / "revisions.yml"
+
+
+@pytest.fixture
+def per_node_tweak_yaml(fixtures_dir: Path) -> Path:
+    """Per-connector / per-cable tweak with a ``@@`` placeholder."""
+    return fixtures_dir / "per_node_tweak.yml"
+
+
+@pytest.fixture
+def hex_color_yaml(fixtures_dir: Path) -> Path:
+    """Cable with a single hex-RGB wire color — exercises the wire-
+    thickness padding regression fix from upstream PR #495."""
+    return fixtures_dir / "hex_color.yml"
+
+
+@pytest.fixture
+def custom_template_yaml(fixtures_dir: Path) -> Path:
+    """Harness referencing a custom HTML template by name."""
+    return fixtures_dir / "custom_template.yml"
+
+
+@pytest.fixture
+def custom_template_dir(fixtures_dir: Path) -> Path:
+    """Directory holding the ``branded.html`` template referenced by
+    ``custom_template.yml``."""
+    return fixtures_dir / "templates"
+
+
+@pytest.fixture
+def dpi_192_yaml(fixtures_dir: Path) -> Path:
+    """``options.output_dpi: 192`` — twice the graphviz default."""
+    return fixtures_dir / "dpi_192.yml"
+
+
+@pytest.fixture
+def workdir(tmp_path: Path, monkeypatch) -> Path:
+    """Like ``tmp_path`` but also chdir's into it so tests that exercise
+    relative-path behavior can use the temp dir as cwd."""
+    monkeypatch.chdir(tmp_path)
+    return tmp_path
+
+
+@pytest.fixture
+def runner():
+    """Click ``CliRunner`` with stderr captured separately, regardless
+    of which Click version is installed.
+
+    * Click 8.0-8.2 needs ``mix_stderr=False`` explicitly.
+    * Click 8.3+ removed the parameter and made separate-capture the
+      always-on default — passing it raises ``TypeError``.
+
+    Tests need separate stderr to assert on banner / error-footer
+    messages, so the fallback ladder isolates that from Click drift.
+    """
+    from click.testing import CliRunner
+
+    try:
+        return CliRunner(mix_stderr=False)
+    except TypeError:
+        return CliRunner()
diff --git a/tests/fixtures/custom_template.yml b/tests/fixtures/custom_template.yml
new file mode 100644
index 000000000..203c4297e
--- /dev/null
+++ b/tests/fixtures/custom_template.yml
@@ -0,0 +1,18 @@
+metadata:
+  template:
+    name: branded
+
+connectors:
+  X1:
+    pinlabels: [A, B]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
diff --git a/tests/fixtures/dpi_192.yml b/tests/fixtures/dpi_192.yml
new file mode 100644
index 000000000..1621b5b96
--- /dev/null
+++ b/tests/fixtures/dpi_192.yml
@@ -0,0 +1,17 @@
+options:
+  output_dpi: 192
+
+connectors:
+  X1:
+    pinlabels: [A, B]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
diff --git a/tests/fixtures/hex_color.yml b/tests/fixtures/hex_color.yml
new file mode 100644
index 000000000..bff749876
--- /dev/null
+++ b/tests/fixtures/hex_color.yml
@@ -0,0 +1,16 @@
+# Single hex-RGB wire color — the upstream PR #495 regression case.
+# Before the fix, ``len(colorstr) > 2`` mis-detected a 7-character
+# hex string as a multi-colored wire and padded it like one.
+connectors:
+  X1:
+    pinlabels: [A]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    colors: ["#ff0000"]
+
+connections:
+  - - X1: [1]
+    - W1: [1]
diff --git a/tests/fixtures/loopback.yml b/tests/fixtures/loopback.yml
new file mode 100644
index 000000000..e53503803
--- /dev/null
+++ b/tests/fixtures/loopback.yml
@@ -0,0 +1,11 @@
+# Loop-only connector that is NOT referenced in any connection set.
+# Upstream PR #496 added auto-instantiation so this still renders;
+# without that fix the connector is silently dropped as an unused
+# template.
+connectors:
+  X1:
+    pincount: 4
+    pinlabels: [A, B, C, D]
+    loops:
+      - [1, 4]
+      - [2, 3]
diff --git a/tests/fixtures/loopback_template.yml b/tests/fixtures/loopback_template.yml
new file mode 100644
index 000000000..db782ddc8
--- /dev/null
+++ b/tests/fixtures/loopback_template.yml
@@ -0,0 +1,21 @@
+# Connector template (``DSub:``) carrying loops, used via the
+# Template.Designator syntax (``DSub.X1`` / ``DSub.X2``). The review
+# fix on PR #1 ensures we don't ALSO auto-instantiate ``DSub`` itself
+# as a phantom floating connector.
+connectors:
+  DSub:
+    type: D-Sub
+    pinlabels: [GND, RX, TX, DTR]
+    loops: [[1, 4]]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.5
+    color_code: DIN
+    wirecount: 2
+
+connections:
+  - - DSub.X1: [2, 3]
+    - W1: [1, 2]
+    - DSub.X2: [3, 2]
diff --git a/tests/fixtures/minimal.yml b/tests/fixtures/minimal.yml
new file mode 100644
index 000000000..0761ce7fb
--- /dev/null
+++ b/tests/fixtures/minimal.yml
@@ -0,0 +1,14 @@
+connectors:
+  X1:
+    pinlabels: [A, B]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
diff --git a/tests/fixtures/per_node_tweak.yml b/tests/fixtures/per_node_tweak.yml
new file mode 100644
index 000000000..ed08e8217
--- /dev/null
+++ b/tests/fixtures/per_node_tweak.yml
@@ -0,0 +1,23 @@
+tweak:
+  placeholder: "@@"
+
+connectors:
+  X1:
+    pinlabels: [A, B]
+    tweak:
+      append:
+        - "@@_extra [color=red, style=dashed];"
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+    tweak:
+      append:
+        - "@@_label [label=\"cable @@\"];"
+
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
diff --git a/tests/fixtures/revisions.yml b/tests/fixtures/revisions.yml
new file mode 100644
index 000000000..09fba566e
--- /dev/null
+++ b/tests/fixtures/revisions.yml
@@ -0,0 +1,26 @@
+metadata:
+  revisions:
+    A:
+      date: 2024-01-01
+      name: Initial draft
+    B:
+      date: 2024-06-15
+      name: Pin labels added
+    C:
+      date: 2026-04-10
+      name: Latest tweak
+
+connectors:
+  X1:
+    pinlabels: [A, B]
+
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+
+connections:
+  - - X1: [1, 2]
+    - W1: [1, 2]
diff --git a/tests/fixtures/templates/branded.html b/tests/fixtures/templates/branded.html
new file mode 100644
index 000000000..ab02fb0ac
--- /dev/null
+++ b/tests/fixtures/templates/branded.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+<head><title>BRANDED-<!-- %filename_stem% --></title></head>
+<body>
+<h1 class="brand-marker">CMDIY HARNESS</h1>
+<!-- %diagram% -->
+<!-- %bom% -->
+</body>
+</html>
diff --git a/tests/test_bom.py b/tests/test_bom.py
new file mode 100644
index 000000000..42ac00181
--- /dev/null
+++ b/tests/test_bom.py
@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""Coverage of BOM aggregation logic."""
+
+from pathlib import Path
+
+import pytest
+
+from wireviz.wireviz import parse
+
+
+def _parse_to_tsv(yaml_str: str, workdir: Path, name: str = "bom") -> str:
+    parse(
+        yaml_str,
+        output_formats=("tsv",),
+        output_dir=workdir,
+        output_name=name,
+    )
+    return (workdir / f"{name}.bom.tsv").read_text()
+
+
+def test_bom_lists_connector(workdir: Path):
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1:
+    type: D-Sub
+    pinlabels: [A, B]
+cables:
+  W1:
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+connections:
+  - [{X1: [1, 2]}, {W1: [1, 2]}]
+""",
+        workdir,
+    )
+    assert "Connector" in tsv
+    assert "X1" in tsv
+    assert "D-Sub" in tsv
+
+
+def test_bom_lists_cable_with_gauge_and_length(workdir: Path):
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {pinlabels: [A]}
+cables:
+  W1:
+    gauge: 0.5 mm2
+    length: 1.5
+    color_code: DIN
+    wirecount: 1
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+""",
+        workdir,
+    )
+    assert "0.5" in tsv  # gauge token preserved
+    assert "1.5" in tsv  # length appears
+    assert "W1" in tsv
+
+
+def test_bom_aggregates_identical_components(workdir: Path):
+    """Two identical D-Sub connectors aggregate into one BOM row with
+    qty=2 and both designators listed."""
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {type: D-Sub, pinlabels: [A]}
+  X2: {type: D-Sub, pinlabels: [A]}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}, {X2: [1]}]
+""",
+        workdir,
+    )
+    rows = tsv.splitlines()
+    dsub_rows = [r for r in rows[1:] if "D-Sub" in r]
+    assert len(dsub_rows) == 1, "identical connectors should aggregate to one row"
+    # Both designators should appear in the same row
+    assert "X1" in dsub_rows[0] and "X2" in dsub_rows[0]
+
+
+def test_bom_separates_connectors_with_different_types(workdir: Path):
+    """A D-Sub and a Molex don't aggregate; they're different components."""
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {type: D-Sub, pinlabels: [A]}
+  X2: {type: Molex KK, pinlabels: [A]}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}, {X2: [1]}]
+""",
+        workdir,
+    )
+    assert "D-Sub" in tsv and "Molex" in tsv
+    rows = tsv.splitlines()
+    assert len([r for r in rows[1:] if "D-Sub" in r]) == 1
+    assert len([r for r in rows[1:] if "Molex" in r]) == 1
+
+
+def test_bom_includes_additional_bom_items(workdir: Path):
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {pinlabels: [A]}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+additional_bom_items:
+  - description: Heat shrink tubing 3mm
+    qty: 4
+    unit: cm
+  - description: Cable tie
+    qty: 6
+""",
+        workdir,
+    )
+    assert "Heat shrink tubing 3mm" in tsv
+    assert "Cable tie" in tsv
+
+
+def test_bom_ignores_components_marked_ignore_in_bom(workdir: Path):
+    """``ignore_in_bom: true`` keeps a connector out of the BOM but
+    still in the diagram."""
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {type: TestPin, pinlabels: [A], ignore_in_bom: true}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+""",
+        workdir,
+    )
+    assert "TestPin" not in tsv
+
+
+def test_bom_part_numbers_appear(workdir: Path):
+    """``pn``, ``mpn``, ``spn`` fields land in the BOM."""
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1:
+    type: D-Sub
+    pinlabels: [A]
+    pn: INTERNAL-001
+    mpn: AMP-12345
+    manufacturer: Amphenol
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+""",
+        workdir,
+    )
+    assert "INTERNAL-001" in tsv
+    assert "AMP-12345" in tsv
+    assert "Amphenol" in tsv
+
+
+def test_bom_bundle_category_emits_one_row_per_wire(workdir: Path):
+    """A cable with ``category: bundle`` produces one BOM row per
+    wire instead of a single cable row."""
+    tsv = _parse_to_tsv(
+        """
+connectors:
+  X1: {pinlabels: [A, B]}
+cables:
+  W1:
+    category: bundle
+    gauge: 0.25 mm2
+    length: 0.1
+    color_code: DIN
+    wirecount: 2
+connections:
+  - [{X1: [1, 2]}, {W1: [1, 2]}]
+""",
+        workdir,
+    )
+    rows = tsv.splitlines()
+    wire_rows = [r for r in rows[1:] if "Wire" in r]
+    assert len(wire_rows) == 2, "bundle should emit one row per wire"
diff --git a/tests/test_cli.py b/tests/test_cli.py
new file mode 100644
index 000000000..a3dee00c0
--- /dev/null
+++ b/tests/test_cli.py
@@ -0,0 +1,269 @@
+# -*- coding: utf-8 -*-
+"""CLI behavior tests via Click's ``CliRunner``.
+
+Every flag, every error path, every input mode (file / stdin / .png).
+The CLI is the user-visible surface — if anything regresses here,
+people notice.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from wireviz.Harness import read_yaml_from_png
+from wireviz.wv_cli import wireviz as cli
+
+
+# Tests in this file use the ``cli_runner`` fixture from conftest.py
+# rather than instantiating CliRunner directly, so the Click 8.0-8.2
+# vs 8.3+ ``mix_stderr`` API drift is handled in one place.
+
+
+# --- Basic file-mode invocations --------------------------------------------
+
+
+def test_cli_file_input_default_formats(runner, minimal_yaml: Path, workdir: Path):
+    """No flags → defaults render html/png/svg/tsv next to the input."""
+    target = workdir / "h.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, [str(target)])
+    assert result.exit_code == 0, result.stderr
+    for ext in ("html", "png", "svg", "bom.tsv"):
+        assert (workdir / f"h.{ext}").exists(), f"{ext} missing"
+
+
+def test_cli_format_flag_subset(runner, minimal_yaml: Path, workdir: Path):
+    """``-f s`` only renders SVG."""
+    target = workdir / "s.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "s", str(target)])
+    assert result.exit_code == 0
+    assert (workdir / "s.svg").exists()
+    assert not (workdir / "s.png").exists()
+    assert not (workdir / "s.html").exists()
+
+
+def test_cli_pdf_format_flag(runner, minimal_yaml: Path, workdir: Path):
+    """``-f P`` (capital P, distinct from lowercase p for PNG) produces PDF."""
+    target = workdir / "p.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "P", str(target)])
+    assert result.exit_code == 0
+    pdf = workdir / "p.pdf"
+    assert pdf.exists()
+    assert pdf.read_bytes()[:5] == b"%PDF-"
+
+
+def test_cli_unknown_format_uses_click_usage_error(runner, minimal_yaml: Path):
+    """An unknown format flag raises ``click.UsageError`` → exit 2 plus
+    the canonical 'Try \\'wireviz -h\\' for help.' footer."""
+    result = runner.invoke(cli, ["-f", "X", str(minimal_yaml)])
+    assert result.exit_code == 2
+    assert "Unknown output format" in result.stderr
+    assert "Try 'wireviz -h' for help" in result.stderr
+
+
+def test_cli_missing_input_file_errors(runner, workdir: Path):
+    """A non-existent input file produces a clean error."""
+    result = runner.invoke(cli, [str(workdir / "does-not-exist.yml")])
+    assert result.exit_code != 0
+    assert "does not exist" in result.stderr.lower()
+
+
+# --- output-dir / output-name -----------------------------------------------
+
+
+def test_cli_output_dir(runner, minimal_yaml: Path, tmp_path: Path):
+    """``-o`` redirects output to a different directory."""
+    out = tmp_path / "out"
+    out.mkdir()
+    result = runner.invoke(
+        cli, ["-f", "s", "-o", str(out), str(minimal_yaml)]
+    )
+    assert result.exit_code == 0
+    assert (out / f"{minimal_yaml.stem}.svg").exists()
+
+
+def test_cli_output_name(runner, minimal_yaml: Path, workdir: Path):
+    """``-O`` overrides the output filename stem."""
+    target = workdir / "input.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "s", "-O", "renamed", str(target)])
+    assert result.exit_code == 0
+    assert (workdir / "renamed.svg").exists()
+    assert not (workdir / "input.svg").exists()
+
+
+# --- stdin / stdout ----------------------------------------------------------
+
+
+def test_cli_stdin_input(runner, minimal_yaml: Path, workdir: Path):
+    """``wireviz -`` reads YAML from stdin."""
+    yaml_text = minimal_yaml.read_text()
+    result = runner.invoke(
+        cli,
+        ["-f", "s", "-O", "stdin_out", "-o", str(workdir), "-"],
+        input=yaml_text,
+    )
+    assert result.exit_code == 0, result.stderr
+    assert (workdir / "stdin_out.svg").exists()
+
+
+def test_cli_stdout_svg(runner, minimal_yaml: Path):
+    """``-O -`` (or ``-o -``) writes the single requested format to stdout."""
+    result = runner.invoke(
+        cli,
+        ["-f", "s", "-O", "-", str(minimal_yaml)],
+    )
+    assert result.exit_code == 0, result.stderr
+    assert result.stdout.lstrip().startswith("<?xml")
+
+
+def test_cli_stdout_multi_format_rejected(runner, minimal_yaml: Path):
+    """Asking for multiple formats with stdout output is a usage error."""
+    result = runner.invoke(
+        cli,
+        ["-f", "shp", "-O", "-", str(minimal_yaml)],
+    )
+    assert result.exit_code == 2
+    assert "Exactly one output format" in result.stderr
+
+
+# --- prepend file -----------------------------------------------------------
+
+
+def test_cli_prepend_file(runner, workdir: Path):
+    """``-p`` concatenates a prepend YAML before the main input —
+    typical use is sharing connector/cable libraries."""
+    library = workdir / "lib.yml"
+    library.write_text(
+        "connectors:\n"
+        "  STDPIN:\n"
+        "    pinlabels: [A, B, C]\n"
+    )
+    main = workdir / "main.yml"
+    main.write_text(
+        "cables:\n"
+        "  W1:\n"
+        "    gauge: 0.25 mm2\n"
+        "    length: 0.1\n"
+        "    color_code: DIN\n"
+        "    wirecount: 3\n"
+        "connections:\n"
+        "  - [{STDPIN: [1, 2, 3]}, {W1: [1, 2, 3]}]\n"
+    )
+    result = runner.invoke(
+        cli, ["-f", "g", "-p", str(library), str(main)]
+    )
+    assert result.exit_code == 0, result.stderr
+    gv = (workdir / "main.gv").read_text()
+    assert "STDPIN" in gv
+
+
+# --- --no-embed-yaml --------------------------------------------------------
+
+
+def test_cli_default_embeds_yaml_in_png(
+    runner, minimal_yaml: Path, workdir: Path
+):
+    """The default CLI behavior embeds the source YAML in PNG output."""
+    target = workdir / "embed.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "p", str(target)])
+    assert result.exit_code == 0
+    extracted = read_yaml_from_png(workdir / "embed.png")
+    assert extracted is not None
+    assert "X1" in extracted
+
+
+def test_cli_no_embed_yaml_flag(runner, minimal_yaml: Path, workdir: Path):
+    """``--no-embed-yaml`` opts out of the chunk."""
+    target = workdir / "plain.yml"
+    target.write_text(minimal_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "p", "--no-embed-yaml", str(target)])
+    assert result.exit_code == 0
+    assert read_yaml_from_png(workdir / "plain.png") is None
+
+
+# --- .png input / round-trip ------------------------------------------------
+
+
+def test_cli_png_input_extracts_yaml(
+    runner, minimal_yaml: Path, workdir: Path
+):
+    """A .png input is auto-detected; the embedded YAML is extracted
+    and re-rendered."""
+    target = workdir / "round.yml"
+    target.write_text(minimal_yaml.read_text())
+    runner.invoke(cli, ["-f", "p", str(target)])
+    # Now feed the PNG back in
+    result = runner.invoke(
+        cli, ["-f", "s", "-O", "from_png", str(workdir / "round.png")]
+    )
+    assert result.exit_code == 0, result.stderr
+    assert (workdir / "from_png.svg").exists()
+    assert "(extracted YAML)" in result.stderr
+
+
+def test_cli_png_input_without_chunk_errors(runner, workdir: Path, tmp_path: Path):
+    """A PNG without the ``wireviz:yaml`` chunk produces a clean
+    UsageError, not a stack trace."""
+    from PIL import Image
+
+    plain = workdir / "plain.png"
+    Image.new("RGB", (8, 8), "white").save(plain)
+    result = runner.invoke(cli, ["-f", "s", str(plain)])
+    assert result.exit_code == 2
+    assert "no embedded WireViz YAML" in result.stderr
+
+
+def test_cli_png_input_corrupt_errors_cleanly(runner, workdir: Path):
+    """A file whose .png suffix lies (not actually a PNG) produces a
+    clean error from the PIL guard."""
+    fake = workdir / "fake.png"
+    fake.write_text("definitely not a PNG")
+    result = runner.invoke(cli, ["-f", "s", str(fake)])
+    assert result.exit_code == 2
+    assert "Could not read PNG" in result.stderr
+
+
+# --- --template-dir ---------------------------------------------------------
+
+
+def test_cli_template_dir(
+    runner,
+    custom_template_yaml: Path,
+    custom_template_dir: Path,
+    workdir: Path,
+):
+    """``-t`` searches the named directory for the template before
+    falling back to source-dir / output-dir / built-ins."""
+    yaml_target = workdir / "custom.yml"
+    yaml_target.write_text(custom_template_yaml.read_text())
+    result = runner.invoke(
+        cli,
+        ["-f", "h", "-t", str(custom_template_dir), str(yaml_target)],
+    )
+    assert result.exit_code == 0, result.stderr
+    html = (workdir / "custom.html").read_text()
+    assert "CMDIY HARNESS" in html, "branded template was not loaded"
+
+
+def test_cli_template_not_found(runner, custom_template_yaml: Path, workdir: Path):
+    """A custom template referenced but not found anywhere errors clearly."""
+    yaml_target = workdir / "missing.yml"
+    yaml_target.write_text(custom_template_yaml.read_text())
+    result = runner.invoke(cli, ["-f", "h", str(yaml_target)])
+    assert result.exit_code != 0
+
+
+# --- version flag -----------------------------------------------------------
+
+
+def test_cli_version_flag_writes_to_stderr(runner):
+    """``-V`` prints the version banner. The banner currently goes to
+    stderr along with all other status messages so stdout stays clean
+    for piping."""
+    result = runner.invoke(cli, ["-V"])
+    assert result.exit_code == 0
+    assert "WireViz" in result.stderr
diff --git a/tests/test_colors.py b/tests/test_colors.py
new file mode 100644
index 000000000..7170ef225
--- /dev/null
+++ b/tests/test_colors.py
@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+"""Coverage of color-code parsing, hex handling, and the wire-thickness
+padding heuristic that PR #495 fixed.
+
+WireViz supports several wire color schemes (DIN 47100, IEC 60757,
+25-pair, TIA/EIA 568) plus user-defined colors and raw hex values."""
+
+import pytest
+
+from wireviz.wv_colors import (
+    COLOR_CODES,
+    get_color_hex,
+    translate_color,
+)
+
+
+# --- Color schemes ----------------------------------------------------------
+
+
+def test_din_color_scheme_first_wires():
+    """DIN 47100 starts WH, BN, GN, YE, GY..."""
+    din = COLOR_CODES["DIN"]
+    assert din[0:5] == ["WH", "BN", "GN", "YE", "GY"]
+
+
+def test_iec_color_scheme_first_wires():
+    """IEC 60757 starts BN, RD, OG, YE, GN..."""
+    iec = COLOR_CODES["IEC"]
+    assert iec[0:5] == ["BN", "RD", "OG", "YE", "GN"]
+
+
+def test_tia_eia_t568b_scheme_present():
+    """T568B is the standard ethernet wiring sequence."""
+    t568b = COLOR_CODES["T568B"]
+    # Should be 8 wires (4 pairs)
+    assert len(t568b) == 8
+
+
+def test_telephone_25_pair_scheme_present():
+    """The 25-pair telephone scheme ('TEL') has 50 entries (25 pairs,
+    each direction)."""
+    tel = COLOR_CODES["TEL"]
+    assert len(tel) == 50
+
+
+# --- Hex color parsing -----------------------------------------------------
+
+
+def test_get_color_hex_for_hex_input():
+    """A 7-char hex string is returned as a one-element list (the
+    PR #495 regression case)."""
+    out = get_color_hex("#ff0000")
+    assert out == ["#ff0000"]
+
+
+def test_get_color_hex_for_named_color():
+    """A 2-letter color abbreviation translates to its hex."""
+    out = get_color_hex("RD")
+    assert isinstance(out, list) and len(out) == 1
+    assert out[0].startswith("#")
+
+
+def test_get_color_hex_for_two_colors():
+    """A 4-char abbreviation 'BNRD' parses as two stripes (BN, RD)
+    and gets a third repeated entry to render as a striped wire — the
+    library's intentional widening rule for exactly-2-color wires."""
+    out = get_color_hex("BNRD")
+    assert len(out) == 3
+    assert out[0] == out[2], "striped form should repeat the first color"
+    assert all(h.startswith("#") for h in out)
+
+
+def test_get_color_hex_pad_widens_single_color_to_3():
+    """``pad=True`` widens a 1-color result to 3 entries so the
+    rendered wire matches the thickness of multi-color wires in the
+    same harness."""
+    out = get_color_hex("BN", pad=True)
+    assert out == [out[0]] * 3
+
+
+def test_get_color_hex_no_pad_keeps_single_color():
+    """``pad=False`` (the default) leaves a single-color wire as one
+    entry. The PR #495 fix ensures hex inputs also count as one,
+    not seven."""
+    assert len(get_color_hex("BN", pad=False)) == 1
+    assert len(get_color_hex("#ff0000", pad=False)) == 1
+
+
+def test_translate_color_short_form():
+    """``translate_color(input, 'SHORT')`` returns the short
+    abbreviation."""
+    assert translate_color("RD", "SHORT") == "RD"
+
+
+def test_translate_color_full_name():
+    """``translate_color(input, 'FULL')`` returns the full english name."""
+    full = translate_color("RD", "FULL")
+    assert "red" in full.lower()
+
+
+def test_translate_color_hex():
+    """``translate_color(input, 'hex')`` returns the lowercase hex."""
+    h = translate_color("RD", "hex")
+    assert h.startswith("#") and h == h.lower()
diff --git a/tests/test_dataclasses.py b/tests/test_dataclasses.py
new file mode 100644
index 000000000..77b92f301
--- /dev/null
+++ b/tests/test_dataclasses.py
@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+"""Coverage of the typed dataclasses in ``DataClasses.py`` — coercion,
+validation, default behavior. These are the schema for everything
+the YAML can express; if any of them drift, every consumer breaks."""
+
+import pytest
+
+from wireviz.DataClasses import Cable, Connector, Image, Options, Tweak
+
+
+# --- Connector --------------------------------------------------------------
+
+
+def test_connector_pincount_inferred_from_pinlabels():
+    """Without an explicit pincount, the connector derives one from
+    the longest of pins/pinlabels/pincolors."""
+    c = Connector(name="X1", pinlabels=["A", "B", "C"])
+    assert c.pincount == 3
+    assert c.pins == [1, 2, 3]
+
+
+def test_connector_explicit_pincount_wins():
+    """An explicit pincount is preserved even when shorter lists are
+    also present."""
+    c = Connector(name="X1", pincount=5, pinlabels=["A", "B"])
+    assert c.pincount == 5
+    assert c.pins == [1, 2, 3, 4, 5]
+
+
+def test_connector_simple_style_caps_pincount_to_1():
+    c = Connector(name="X1", style="simple", pinlabels=["A"])
+    assert c.pincount == 1
+
+
+def test_connector_simple_style_rejects_multi_pin():
+    with pytest.raises(Exception, match="simple may only have one pin"):
+        Connector(name="X1", style="simple", pincount=2)
+
+
+def test_connector_no_pin_info_raises():
+    """A connector with no pincount, pins, pinlabels, or pincolors
+    can't be rendered and is rejected at construction."""
+    with pytest.raises(Exception, match="at least one"):
+        Connector(name="X1")
+
+
+def test_connector_duplicate_pins_raise():
+    with pytest.raises(Exception, match="Pins are not unique"):
+        Connector(name="X1", pins=[1, 1, 2])
+
+
+# --- Cable ------------------------------------------------------------------
+
+
+def test_cable_gauge_str_with_unit_parsed():
+    """``gauge: '0.25 mm2'`` splits into the numeric prefix and a unit
+    string (with the U+00B2 superscript-2 substitution applied).
+    Note: ``gauge`` is kept as a string after splitting — the project's
+    convention is to preserve the original numeric token for display.
+    """
+    c = Cable(name="W1", gauge="0.25 mm2", length=0.1, color_code="DIN", wirecount=2)
+    assert c.gauge == "0.25"
+    assert c.gauge_unit == "mm²"
+
+
+def test_cable_gauge_awg_uppercased():
+    c = Cable(name="W1", gauge="22 AWG", length=0.1, color_code="DIN", wirecount=2)
+    assert c.gauge == "22"
+    assert c.gauge_unit == "AWG"
+
+
+def test_cable_gauge_numeric_assumes_mm2():
+    """A bare numeric gauge gets ``mm²`` as the default unit and stays
+    numeric (no string round-trip happens for numeric inputs)."""
+    c = Cable(name="W1", gauge=0.5, length=0.1, color_code="DIN", wirecount=2)
+    assert c.gauge == 0.5
+    assert c.gauge_unit == "mm²"
+
+
+def test_cable_length_with_unit():
+    c = Cable(
+        name="W1",
+        gauge="0.25 mm2",
+        length="2.5 ft",
+        color_code="DIN",
+        wirecount=2,
+    )
+    assert c.length == 2.5
+    assert c.length_unit == "ft"
+
+
+def test_cable_length_non_numeric_raises():
+    with pytest.raises(Exception, match="Length must be a number"):
+        Cable(
+            name="W1",
+            gauge="0.25 mm2",
+            length="not a number",
+            color_code="DIN",
+            wirecount=2,
+        )
+
+
+# --- Tweak coercion --------------------------------------------------------
+
+
+def test_tweak_default_fields():
+    """Default ``Tweak()`` has all-None fields — the no-tweak case."""
+    t = Tweak()
+    assert t.placeholder is None
+    assert t.override is None
+    assert t.append is None
+
+
+def test_connector_tweak_dict_coerced_to_tweak():
+    """A dict literal in the YAML position for ``tweak:`` is coerced
+    into a Tweak instance by ``Connector.__post_init__``."""
+    c = Connector(
+        name="X1",
+        pinlabels=["A"],
+        tweak={"placeholder": "@@", "append": ["@@_extra"]},
+    )
+    assert isinstance(c.tweak, Tweak)
+    assert c.tweak.placeholder == "@@"
+    assert c.tweak.append == ["@@_extra"]
+
+
+def test_cable_tweak_dict_coerced_to_tweak():
+    c = Cable(
+        name="W1",
+        gauge="0.25 mm2",
+        length=0.1,
+        color_code="DIN",
+        wirecount=2,
+        tweak={"append": ["foo"]},
+    )
+    assert isinstance(c.tweak, Tweak)
+
+
+# --- Options ---------------------------------------------------------------
+
+
+def test_options_default_dpi():
+    """``output_dpi`` defaults to 96.0 — Graphviz's own default for
+    non-PostScript renderers, so existing harnesses are unchanged."""
+    o = Options()
+    assert o.output_dpi == 96.0
+
+
+def test_options_dpi_can_be_none():
+    """``output_dpi: None`` is a valid value meaning "let graphviz
+    pick its renderer-specific default" (see the PR #4 review fix)."""
+    o = Options(output_dpi=None)
+    assert o.output_dpi is None
+
+
+def test_options_bgcolor_defaults_cascade():
+    """When the per-element bgcolor fields are unset, they cascade
+    from ``bgcolor`` (white by default)."""
+    o = Options()
+    assert o.bgcolor == "WH"
+    # bgcolor_node falls back to bgcolor
+    assert o.bgcolor_node == "WH"
+    # bgcolor_connector falls back to bgcolor_node
+    assert o.bgcolor_connector == "WH"
+
+
+# --- Image -----------------------------------------------------------------
+
+
+def test_image_scale_default():
+    """When neither width nor height is set, scale defaults to 'false'."""
+    img = Image(src="logo.png")
+    assert img.scale == "false"
+
+
+def test_image_scale_both_when_dimensions_given():
+    """Explicit width + height locks scale to 'both'."""
+    img = Image(src="logo.png", width=100, height=80)
+    assert img.scale == "both"
+    # And fixedsize gets set automatically
+    assert img.fixedsize is True
diff --git a/tests/test_harness.py b/tests/test_harness.py
new file mode 100644
index 000000000..f4957401c
--- /dev/null
+++ b/tests/test_harness.py
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""Coverage of the ``Harness`` class itself — the in-memory harness
+graph that ``parse()`` builds and that the GUI will likely call into
+directly."""
+
+from pathlib import Path
+
+import pytest
+
+from wireviz.DataClasses import Metadata, Options, Tweak
+from wireviz.Harness import Harness, _embed_yaml_in_png, read_yaml_from_png
+from wireviz.wireviz import parse
+
+
+def _new_harness() -> Harness:
+    return Harness(
+        metadata=Metadata(),
+        options=Options(),
+        tweak=Tweak(),
+    )
+
+
+def test_empty_harness_constructs():
+    """A bare ``Harness()`` builds with empty containers."""
+    h = _new_harness()
+    assert h.connectors == {}
+    assert h.cables == {}
+    assert h.mates == []
+    assert h.additional_bom_items == []
+
+
+def test_add_connector_appends_to_connectors():
+    h = _new_harness()
+    h.add_connector("X1", pinlabels=["A", "B"])
+    assert "X1" in h.connectors
+    assert h.connectors["X1"].pinlabels == ["A", "B"]
+
+
+def test_add_cable_appends_to_cables():
+    h = _new_harness()
+    h.add_cable("W1", gauge="0.25 mm2", length=0.1, color_code="DIN", wirecount=2)
+    assert "W1" in h.cables
+    assert h.cables["W1"].wirecount == 2
+
+
+def test_add_connector_rejects_old_attr_names():
+    """Renamed-since-v0.2 attributes raise a clear error rather than
+    silently being ignored."""
+    h = _new_harness()
+    with pytest.raises(ValueError, match="pinout"):
+        h.add_connector("X1", pinout=["A", "B"])
+    with pytest.raises(ValueError, match="pinnumbers"):
+        h.add_connector("X2", pinnumbers=[1, 2])
+
+
+def test_render_dict_shapes(minimal_yaml: Path):
+    """``Harness._render`` returns a dict with the right key/value
+    shapes for each format. This is the contract the stdout dispatch
+    relies on."""
+    h = parse(minimal_yaml, return_types="harness")
+    outputs = h._render(("svg", "png", "gv", "tsv"))
+    assert isinstance(outputs["svg"], str)
+    assert isinstance(outputs["png"], bytes)
+    assert isinstance(outputs["gv"], str)
+    assert isinstance(outputs["tsv"], str)
+    assert outputs["svg"].lstrip().startswith("<?xml")
+    assert outputs["png"].startswith(b"\x89PNG\r\n")
+    assert outputs["gv"].startswith("graph {")
+
+
+def test_render_str_fmt_normalized_to_tuple(minimal_yaml: Path):
+    """A bare string ``fmt`` works the same as a one-tuple. Was a
+    latent bug before the str-normalization fix on PR #4."""
+    h = parse(minimal_yaml, return_types="harness")
+    outputs = h._render("svg")  # str, not tuple
+    assert "svg" in outputs
+    assert isinstance(outputs["svg"], str)
+
+
+def test_render_html_threads_png_b64_inline(minimal_yaml: Path):
+    """When both ``html`` and ``png`` are rendered in one call, the
+    HTML's ``%diagram_png_b64%`` placeholder gets the in-memory PNG
+    bytes inlined as a data URI rather than reading from disk."""
+    h = parse(minimal_yaml, return_types="harness")
+    outputs = h._render(("html", "png"))
+    # HTML doesn't contain %diagram_png_b64% by default (the
+    # built-in simple template uses %diagram%), but the underlying
+    # mechanism is exercised by the dpi/branded template tests
+    # elsewhere. What we can assert here is the HTML is a complete
+    # document that doesn't reference the .png as a sibling file.
+    assert "<svg " in outputs["html"]
+
+
+def test_output_to_file(minimal_yaml: Path, workdir: Path):
+    """``Harness.output(filename=path, fmt=...)`` writes files."""
+    h = parse(minimal_yaml, return_types="harness")
+    h.output(
+        filename=workdir / "harness",
+        fmt=("svg", "gv"),
+    )
+    assert (workdir / "harness.svg").exists()
+    assert (workdir / "harness.gv").exists()
+
+
+def test_output_to_stdout_writes_bytes_or_text(minimal_yaml: Path, capsys):
+    """``Harness.output(filename=None)`` writes to stdout. SVG (str)
+    goes to ``sys.stdout``; PNG (bytes) goes to ``sys.stdout.buffer``."""
+    h = parse(minimal_yaml, return_types="harness")
+    h.output(filename=None, fmt=("svg",))
+    captured = capsys.readouterr()
+    assert captured.out.lstrip().startswith("<?xml")
+
+
+def test_embed_yaml_in_png_round_trip():
+    """``_embed_yaml_in_png`` + ``read_yaml_from_png`` round-trip a
+    YAML payload through PNG bytes."""
+    from PIL import Image
+    import io
+
+    # Make a tiny PNG to embed into
+    buf = io.BytesIO()
+    Image.new("RGB", (4, 4), "white").save(buf, format="PNG")
+    yaml_payload = "connectors:\n  X1:\n    pinlabels: [A]\n"
+    annotated = _embed_yaml_in_png(buf.getvalue(), yaml_payload)
+    assert annotated.startswith(b"\x89PNG\r\n")
+
+    # Round trip via a temp file
+    import tempfile, os
+
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+        f.write(annotated)
+        tmp = f.name
+    try:
+        recovered = read_yaml_from_png(tmp)
+        assert recovered == yaml_payload
+    finally:
+        os.unlink(tmp)
+
+
+def test_read_yaml_from_png_returns_none_if_missing(workdir: Path):
+    """A plain PNG with no ``wireviz:yaml`` chunk returns ``None``."""
+    from PIL import Image
+
+    plain = workdir / "plain.png"
+    Image.new("RGB", (4, 4), "white").save(plain)
+    assert read_yaml_from_png(plain) is None
diff --git a/tests/test_parse.py b/tests/test_parse.py
new file mode 100644
index 000000000..945e037d9
--- /dev/null
+++ b/tests/test_parse.py
@@ -0,0 +1,259 @@
+# -*- coding: utf-8 -*-
+"""Coverage of the public ``wireviz.parse()`` API surface — input
+shapes, output shapes, and the various optional parameters.
+
+Anything the GUI or other programmatic callers might lean on goes
+here. The CLI lives in test_cli.py.
+"""
+
+from pathlib import Path
+
+import pytest
+import yaml
+
+from wireviz.Harness import Harness
+from wireviz.wireviz import parse
+
+
+# --- Input shapes (Path / str / dict) ---------------------------------------
+
+
+def test_parse_path_input(minimal_yaml: Path, workdir: Path):
+    """``parse()`` accepts a Path-like for the YAML input."""
+    parse(
+        minimal_yaml,
+        output_formats=("svg",),
+        output_dir=workdir,
+        output_name="p",
+        embed_yaml=False,
+    )
+    assert (workdir / "p.svg").exists()
+
+
+def test_parse_string_input(minimal_yaml: Path, workdir: Path):
+    """``parse()`` accepts a YAML string for the YAML input."""
+    yaml_str = minimal_yaml.read_text()
+    parse(
+        yaml_str,
+        output_formats=("svg",),
+        output_dir=workdir,
+        output_name="s",
+        embed_yaml=False,
+    )
+    assert (workdir / "s.svg").exists()
+
+
+def test_parse_dict_input(minimal_yaml: Path, workdir: Path):
+    """``parse()`` accepts a pre-parsed dict for the YAML input."""
+    data = yaml.safe_load(minimal_yaml.read_text())
+    parse(
+        data,
+        output_formats=("svg",),
+        output_dir=workdir,
+        output_name="d",
+        embed_yaml=False,
+    )
+    assert (workdir / "d.svg").exists()
+
+
+def test_parse_rejects_non_dict_yaml(workdir: Path):
+    """A YAML string that doesn't decode to a dict at the top level
+    raises TypeError rather than silently producing nothing."""
+    with pytest.raises(TypeError, match="dict as top-level YAML"):
+        parse(
+            "- just\n- a\n- list\n",
+            output_formats=("svg",),
+            output_dir=workdir,
+            output_name="bad",
+        )
+
+
+# --- output_formats variations ----------------------------------------------
+
+
+def test_parse_output_formats_string(minimal_yaml: Path, workdir: Path):
+    """A bare string ``output_formats="svg"`` is accepted; the underlying
+    ``Harness.output()`` normalizes it to a one-tuple."""
+    parse(
+        minimal_yaml,
+        output_formats="svg",
+        output_dir=workdir,
+        output_name="str",
+        embed_yaml=False,
+    )
+    assert (workdir / "str.svg").exists()
+
+
+def test_parse_output_formats_tuple(minimal_yaml: Path, workdir: Path):
+    parse(
+        minimal_yaml,
+        output_formats=("svg", "png"),
+        output_dir=workdir,
+        output_name="t",
+        embed_yaml=False,
+    )
+    assert (workdir / "t.svg").exists()
+    assert (workdir / "t.png").exists()
+
+
+def test_parse_output_formats_list(minimal_yaml: Path, workdir: Path):
+    parse(
+        minimal_yaml,
+        output_formats=["svg", "png"],
+        output_dir=workdir,
+        output_name="l",
+        embed_yaml=False,
+    )
+    assert (workdir / "l.svg").exists()
+    assert (workdir / "l.png").exists()
+
+
+def test_parse_no_outputs_or_returns_raises(minimal_yaml: Path):
+    """Calling ``parse()`` with neither ``output_formats`` nor
+    ``return_types`` is a usage error."""
+    with pytest.raises(Exception, match="No output formats or return types"):
+        parse(minimal_yaml)
+
+
+# --- return_types ------------------------------------------------------------
+
+
+def test_parse_returns_harness_object(minimal_yaml: Path):
+    """``return_types="harness"`` yields a populated Harness instance."""
+    h = parse(minimal_yaml, return_types="harness")
+    assert isinstance(h, Harness)
+    assert "X1" in h.connectors
+    assert "W1" in h.cables
+
+
+def test_parse_returns_svg_string(minimal_yaml: Path):
+    """``return_types="svg"`` yields an SVG string."""
+    svg = parse(minimal_yaml, return_types="svg")
+    assert isinstance(svg, str)
+    assert svg.lstrip().startswith("<?xml")
+
+
+def test_parse_returns_png_bytes(minimal_yaml: Path):
+    """``return_types="png"`` yields PNG bytes."""
+    png = parse(minimal_yaml, return_types="png")
+    assert isinstance(png, bytes)
+    assert png.startswith(b"\x89PNG\r\n")
+
+
+def test_parse_returns_tuple_for_multiple(minimal_yaml: Path):
+    """Multiple return_types yields a tuple, not a single value."""
+    result = parse(minimal_yaml, return_types=("svg", "harness"))
+    assert isinstance(result, tuple) and len(result) == 2
+    svg, h = result
+    assert isinstance(svg, str)
+    assert isinstance(h, Harness)
+
+
+# --- source_path semantics ---------------------------------------------------
+
+
+def test_source_path_autofills_from_path_input(minimal_yaml: Path):
+    """When the input is a Path, source_path is auto-filled and visible
+    on the returned Harness — the docstring promises this."""
+    h = parse(minimal_yaml, return_types="harness")
+    assert h.source_path is not None
+    assert Path(h.source_path).resolve() == minimal_yaml.resolve()
+
+
+def test_source_path_explicit_overrides_inp(minimal_yaml: Path, tmp_path: Path):
+    """An explicit ``source_path`` kwarg is preserved verbatim and not
+    silently overwritten by the auto-fill logic."""
+    explicit = tmp_path / "stand-in.yml"
+    h = parse(minimal_yaml, return_types="harness", source_path=explicit)
+    assert h.source_path == explicit
+
+
+def test_source_path_string_input_no_autofill():
+    """When the input is a YAML string (no source path available),
+    source_path stays None unless explicitly passed."""
+    h = parse(
+        "connectors:\n  X1:\n    pinlabels: [A]\n"
+        "cables:\n  W1:\n    gauge: 0.25 mm2\n    length: 0.1\n"
+        "    color_code: DIN\n    wirecount: 1\n"
+        "connections:\n  - [{X1: [1]}, {W1: [1]}]\n",
+        return_types="harness",
+    )
+    assert h.source_path is None
+
+
+# --- output_dir / output_name conventions -----------------------------------
+
+
+def test_output_dir_defaults_to_input_parent(minimal_yaml: Path, tmp_path: Path):
+    """Without an explicit ``output_dir``, files are written next to
+    the input YAML."""
+    target = tmp_path / "harness.yml"
+    target.write_text(minimal_yaml.read_text())
+    parse(target, output_formats=("svg",), embed_yaml=False)
+    assert (tmp_path / "harness.svg").exists()
+
+
+def test_output_name_defaults_to_input_stem(minimal_yaml: Path, tmp_path: Path):
+    """Without an explicit ``output_name``, the input file's stem is used."""
+    target = tmp_path / "harness.yml"
+    target.write_text(minimal_yaml.read_text())
+    parse(target, output_formats=("svg",), embed_yaml=False)
+    assert (tmp_path / "harness.svg").exists()
+
+
+# --- embed_yaml flag --------------------------------------------------------
+
+
+def test_embed_yaml_default_true(minimal_yaml: Path, workdir: Path):
+    """By default, PNG output carries the embedded YAML chunk."""
+    from wireviz.Harness import read_yaml_from_png
+
+    parse(
+        minimal_yaml,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="default",
+    )
+    extracted = read_yaml_from_png(workdir / "default.png")
+    assert extracted is not None and "X1" in extracted
+
+
+def test_embed_yaml_false_strips_chunk(minimal_yaml: Path, workdir: Path):
+    """``embed_yaml=False`` produces a plain PNG with no source chunk."""
+    from wireviz.Harness import read_yaml_from_png
+
+    parse(
+        minimal_yaml,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="plain",
+        embed_yaml=False,
+    )
+    assert read_yaml_from_png(workdir / "plain.png") is None
+
+
+# --- additional_bom_items section ------------------------------------------
+
+
+def test_additional_bom_items_appear_in_tsv(workdir: Path):
+    """Items in ``additional_bom_items:`` are aggregated into the BOM."""
+    yaml_str = """
+connectors:
+  X1: {pinlabels: [A, B]}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 2}
+connections:
+  - [{X1: [1, 2]}, {W1: [1, 2]}]
+additional_bom_items:
+  - description: Heat shrink tubing
+    qty: 4
+    unit: cm
+"""
+    parse(
+        yaml_str,
+        output_formats=("tsv",),
+        output_dir=workdir,
+        output_name="extra",
+    )
+    tsv = (workdir / "extra.bom.tsv").read_text()
+    assert "Heat shrink tubing" in tsv
diff --git a/tests/test_regressions.py b/tests/test_regressions.py
new file mode 100644
index 000000000..23815a5ba
--- /dev/null
+++ b/tests/test_regressions.py
@@ -0,0 +1,482 @@
+# -*- coding: utf-8 -*-
+"""One test per upstream-PR port + every gemini-code-assist review fix.
+
+These are the most valuable tests in the suite — they pin down the
+exact behavior we shipped through PRs #1–#10 so we can never silently
+regress to the pre-fix state. Each test cites the PR (or PRs) it
+guards.
+"""
+
+from pathlib import Path
+
+import pytest
+import yaml
+from PIL import Image
+
+from wireviz.DataClasses import Cable, Options
+from wireviz.Harness import Harness, read_yaml_from_png
+from wireviz.wireviz import parse
+from wireviz.wv_cli import wireviz as cli
+from wireviz.wv_colors import get_color_hex
+from wireviz.wv_html import _latest_revision
+
+
+# ===========================================================================
+# Bug fixes from upstream PR #1 (4 fixes bundled)
+# ===========================================================================
+
+
+def test_pr443_svg_mime_type_in_data_uri():
+    """Upstream PR #443. SVG images embedded as base64 data URIs need
+    the MIME type ``image/svg+xml``, not ``image/svg`` — browsers
+    refuse to render the latter."""
+    from wireviz.svgembed import get_mime_subtype
+
+    assert get_mime_subtype("logo.svg") == "svg+xml"
+    assert get_mime_subtype("logo.jpg") == "jpeg"
+    assert get_mime_subtype("logo.tif") == "tiff"
+
+
+def test_pr473_template_path_search_includes_source_dir(
+    custom_template_yaml, custom_template_dir, tmp_path: Path
+):
+    """Upstream PR #473. A custom template referenced by name resolves
+    against the YAML source directory before falling back to built-ins.
+
+    Set up: copy the YAML and template into the same directory, then
+    render with output_dir pointing elsewhere — the template should
+    still be found via source_path."""
+    src = tmp_path / "src"
+    out = tmp_path / "out"
+    src.mkdir()
+    out.mkdir()
+    (src / "input.yml").write_text(custom_template_yaml.read_text())
+    (src / "branded.html").write_text(
+        (custom_template_dir / "branded.html").read_text()
+    )
+    parse(
+        src / "input.yml",
+        output_formats=("html",),
+        output_dir=out,
+        output_name="render",
+    )
+    rendered = (out / "render.html").read_text()
+    assert "CMDIY HARNESS" in rendered, (
+        "template must resolve from source_path.parent, not just output_dir"
+    )
+
+
+def test_pr495_hex_color_does_not_pad_wire_thickness(workdir: Path, hex_color_yaml: Path):
+    """Upstream PR #495. A 7-character hex color was misdetected as a
+    multi-color stripe, padding single-color wires to 3x thickness.
+
+    Validate the underlying ``get_color_hex`` returns 1 entry for a
+    hex input, and the rendered .gv reflects single-thickness."""
+    assert len(get_color_hex("#ff0000")) == 1
+
+    parse(
+        hex_color_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="hex",
+    )
+    gv = (workdir / "hex.gv").read_text()
+    # The single-color wire should not be rendered with the striped
+    # 3-row table that multi-color wires use.
+    assert "#ff0000" in gv
+
+
+def test_pr496_loop_only_connector_auto_instantiated(
+    workdir: Path, loopback_yaml: Path
+):
+    """Upstream PR #496. A connector with ``loops:`` and no connection-
+    set reference should still render (auto-instantiated) — before the
+    fix it was silently dropped as an unused template."""
+    parse(
+        loopback_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="lo",
+    )
+    gv = (workdir / "lo.gv").read_text()
+    assert "X1 [label=" in gv, "loop-only connector was not rendered"
+
+
+def test_pr1_review_loop_template_with_designator_no_phantom(
+    workdir: Path, loopback_template_yaml: Path
+):
+    """PR #1 review fix. When a connector template carrying ``loops:``
+    is used via Template.Designator (e.g. ``DSub.X1``), we instantiate
+    X1 and X2 — but NOT a phantom ``DSub`` connector with duplicate
+    loops.
+
+    Pre-fix, the auto-instantiation pass would re-add ``DSub`` because
+    the template name didn't match any literal designator in
+    harness.connectors."""
+    h = parse(loopback_template_yaml, return_types="harness")
+    assert "X1" in h.connectors
+    assert "X2" in h.connectors
+    assert "DSub" not in h.connectors, "phantom template instance"
+
+
+# ===========================================================================
+# Upstream PR #321 (port-321) — stdin/stdout streaming
+# ===========================================================================
+
+
+def test_pr321_stdout_writes_svg_text(runner, minimal_yaml: Path):
+    """Single-format stdout writes the rendered text to ``sys.stdout``."""
+    result = runner.invoke(cli, ["-f", "s", "-O", "-", str(minimal_yaml)])
+    assert result.exit_code == 0
+    assert result.stdout.lstrip().startswith("<?xml")
+
+
+def test_pr321_stdout_writes_png_bytes(runner, minimal_yaml: Path):
+    """Single-format stdout writes PNG bytes to ``sys.stdout.buffer``."""
+    result = runner.invoke(cli, ["-f", "p", "-O", "-", str(minimal_yaml)])
+    assert result.exit_code == 0
+    # CliRunner exposes binary stdout via .stdout_bytes
+    out = result.stdout_bytes if hasattr(result, "stdout_bytes") else result.stdout.encode("latin-1")
+    assert out.startswith(b"\x89PNG\r\n")
+
+
+def test_pr321_review_fmt_str_normalized_to_tuple(minimal_yaml: Path):
+    """PR #2 review fix. ``output_formats="svg"`` (a bare string) used
+    to iterate over characters; now it's normalized to ``("svg",)``."""
+    h = parse(minimal_yaml, return_types="harness")
+    outputs = h._render("svg")  # bare string
+    assert "svg" in outputs and isinstance(outputs["svg"], str)
+
+
+def test_pr321_review_log_to_stderr(runner, minimal_yaml: Path):
+    """PR #2 review fix. CLI log lines go to stderr so piped stdout
+    stays a valid SVG/PNG/etc."""
+    result = runner.invoke(cli, ["-f", "s", "-O", "-", str(minimal_yaml)])
+    assert "WireViz" in result.stderr  # banner on stderr
+    assert "WireViz" not in result.stdout.lstrip("<")[:100]  # not on stdout
+
+
+# ===========================================================================
+# Upstream PR #444 — --template-dir
+# ===========================================================================
+
+
+def test_pr444_template_dir_first_in_search_order(
+    runner, custom_template_yaml: Path, custom_template_dir: Path, workdir: Path
+):
+    """Upstream PR #444. ``-t`` adds an explicit directory to the
+    front of the template search path."""
+    yaml_target = workdir / "in.yml"
+    yaml_target.write_text(custom_template_yaml.read_text())
+    result = runner.invoke(
+        cli,
+        ["-f", "h", "-t", str(custom_template_dir), str(yaml_target)],
+    )
+    assert result.exit_code == 0, result.stderr
+    html = (workdir / "in.html").read_text()
+    assert "CMDIY HARNESS" in html
+
+
+# ===========================================================================
+# Upstream PR #379 — output_dpi
+# ===========================================================================
+
+
+def test_pr379_output_dpi_emits_dpi_graph_attr(workdir: Path, dpi_192_yaml: Path):
+    """Upstream PR #379. ``options.output_dpi: 192`` shows up as a
+    ``dpi=192`` attribute in the generated .gv."""
+    parse(
+        dpi_192_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="dpi",
+    )
+    gv = (workdir / "dpi.gv").read_text()
+    assert "dpi=192" in gv
+
+
+def test_pr379_review_dpi_none_omits_attribute(workdir: Path):
+    """PR #4 review fix. ``output_dpi: null`` in YAML omits the dpi
+    graph attribute entirely (lets graphviz pick its renderer-default
+    96 for PNG) instead of emitting the literal string 'None'."""
+    yaml_str = """
+options:
+  output_dpi: null
+connectors:
+  X1: {pinlabels: [A]}
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+"""
+    parse(
+        yaml_str,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="nodpi",
+    )
+    gv = (workdir / "nodpi.gv").read_text()
+    assert "dpi=" not in gv
+    assert "None" not in gv
+
+
+def test_pr379_default_dpi_is_96(workdir: Path, minimal_yaml: Path):
+    """Default ``Options.output_dpi`` is 96.0 (graphviz default for
+    non-PostScript), so existing harnesses are unchanged."""
+    parse(
+        minimal_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="default",
+    )
+    gv = (workdir / "default.gv").read_text()
+    assert "dpi=96.0" in gv
+
+
+# ===========================================================================
+# Upstream PR #234 — YAML embedded in PNG
+# ===========================================================================
+
+
+def test_pr234_png_embeds_yaml_chunk(workdir: Path, minimal_yaml: Path):
+    """Upstream PR #234. Default-rendered PNGs carry the YAML source
+    in a ``wireviz:yaml`` iTXt chunk."""
+    parse(
+        minimal_yaml,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="emb",
+    )
+    extracted = read_yaml_from_png(workdir / "emb.png")
+    assert extracted is not None
+    assert "X1" in extracted and "W1" in extracted
+
+
+def test_pr234_round_trip_via_png(workdir: Path, minimal_yaml: Path):
+    """Render → PNG → re-extract → compare YAML round-trips byte-for-byte
+    (modulo what the prepend / dict-dump path normalizes)."""
+    yaml_text = minimal_yaml.read_text()
+    parse(
+        yaml_text,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="rt",
+    )
+    extracted = read_yaml_from_png(workdir / "rt.png")
+    # Should round-trip the original text exactly (YAML strings are
+    # passed through unchanged for embed)
+    assert extracted == yaml_text
+
+
+def test_pr234_review_im_info_preserved_through_embed(workdir: Path):
+    """PR #5 review fix. Re-encoding the PNG to add the iTXt chunk
+    doesn't lose existing metadata chunks (DPI etc)."""
+    from wireviz.Harness import _embed_yaml_in_png
+    import io
+
+    # Make a PNG with a DPI hint
+    buf = io.BytesIO()
+    Image.new("RGB", (16, 16), "red").save(buf, format="PNG", dpi=(192, 192))
+    annotated = _embed_yaml_in_png(buf.getvalue(), "x: 1\n")
+    # The DPI tuple should survive the re-encode
+    annotated_im = Image.open(io.BytesIO(annotated))
+    annotated_im.load()
+    # PNG pHYs chunk stores DPI as pixels-per-meter; round-tripping
+    # introduces a tiny float quantization. Approximate is enough.
+    dpi = annotated_im.info.get("dpi")
+    assert dpi is not None and abs(dpi[0] - 192.0) < 0.1
+
+
+def test_pr234_review_corrupt_png_clean_error(runner, workdir: Path):
+    """PR #5 review fix. A non-PNG file with a .png suffix fed as input
+    raises ``click.UsageError`` rather than spewing a stack trace."""
+    fake = workdir / "fake.png"
+    fake.write_text("definitely not a PNG")
+    result = runner.invoke(cli, ["-f", "s", str(fake)])
+    assert result.exit_code == 2
+    assert "Could not read PNG" in result.stderr
+
+
+# ===========================================================================
+# Upstream PR #492 — <!-- %revision% --> placeholder
+# ===========================================================================
+
+
+def test_pr492_latest_revision_returns_last_dict_key():
+    """Upstream PR #492. ``_latest_revision`` returns the most-recently
+    declared revision name (which Python preserves via dict insertion
+    order)."""
+    md = {"revisions": {"A": {}, "B": {}, "C": {}}}
+    assert _latest_revision(md) == "C"
+
+
+def test_pr492_review_handles_scalar_revisions():
+    """PR #6 review fix. A scalar ``revisions: v1.0`` value used to
+    return ``'0'`` (last char of str). Now returns the whole scalar."""
+    assert _latest_revision({"revisions": "v1.0"}) == "v1.0"
+    assert _latest_revision({"revisions": 42}) == "42"
+
+
+def test_pr492_review_handles_missing_or_empty_revisions():
+    """PR #6 review fix. None / missing / empty containers all return
+    empty string instead of raising."""
+    assert _latest_revision({}) == ""
+    assert _latest_revision({"revisions": None}) == ""
+    assert _latest_revision({"revisions": {}}) == ""
+    assert _latest_revision({"revisions": []}) == ""
+
+
+# ===========================================================================
+# Upstream PR #357 — per-connector / per-cable tweak with placeholder
+# ===========================================================================
+
+
+def test_pr357_per_node_tweak_substitutes_placeholder(
+    workdir: Path, per_node_tweak_yaml: Path
+):
+    """Upstream PR #357. A per-connector ``tweak.append`` line with
+    a placeholder ``@@`` gets the actual connector designator
+    substituted in the rendered .gv."""
+    parse(
+        per_node_tweak_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="t",
+    )
+    gv = (workdir / "t.gv").read_text()
+    assert "X1_extra" in gv, "per-connector @@_extra didn't substitute"
+    assert "W1_label" in gv, "per-cable @@_label didn't substitute"
+    assert "cable W1" in gv, "@@ inside string value didn't substitute"
+
+
+def test_pr357_review_none_override_value_no_crash(workdir: Path):
+    """PR #7 review fix. An override value of ``null`` (YAML deletion
+    sentinel) used to crash the rph lambda with AttributeError."""
+    yaml_str = """
+tweak:
+  placeholder: "@@"
+connectors:
+  X1:
+    pinlabels: [A]
+    tweak:
+      override:
+        "@@":
+          color: null
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+"""
+    # Should not raise
+    parse(yaml_str, output_formats=("gv",), output_dir=workdir, output_name="ndiv")
+
+
+def test_pr357_review_conflict_error_includes_values(workdir: Path):
+    """PR #10 review fix. The conflict error reports both the existing
+    and the new value, so users can resolve without spelunking."""
+    yaml_str = """
+tweak:
+  placeholder: "@@"
+  override:
+    X1:
+      color: "red"
+connectors:
+  X1:
+    pincount: 1
+    tweak:
+      override:
+        "@@":
+          color: "blue"
+cables:
+  W1: {gauge: 0.25 mm2, length: 0.1, color_code: DIN, wirecount: 1}
+connections:
+  - [{X1: [1]}, {W1: [1]}]
+"""
+    with pytest.raises(ValueError, match="'blue'.*conflicts.*'red'"):
+        parse(
+            yaml_str,
+            output_formats=("gv",),
+            output_dir=workdir,
+            output_name="conf",
+        )
+
+
+# ===========================================================================
+# Upstream PR #367 — PDF output
+# ===========================================================================
+
+
+def test_pr367_pdf_format_produces_valid_pdf(workdir: Path, minimal_yaml: Path):
+    """Upstream PR #367. ``-f P`` (capital P) renders a valid PDF."""
+    parse(
+        minimal_yaml,
+        output_formats=("pdf",),
+        output_dir=workdir,
+        output_name="p",
+        embed_yaml=False,
+    )
+    pdf = workdir / "p.pdf"
+    assert pdf.exists()
+    assert pdf.read_bytes()[:5] == b"%PDF-"
+
+
+def test_pr367_review_pdf_docstring_says_diagram_only():
+    """PR #8 review fix. The parse() docstring's PDF entry was updated
+    to be honest about the implementation: PDF is diagram-only,
+    no BOM (HTML covers that)."""
+    docstring = parse.__doc__ or ""
+    pdf_line = next(
+        (line for line in docstring.splitlines() if '"pdf"' in line), ""
+    )
+    assert "no BOM" in pdf_line or "diagram, as a PDF" in pdf_line
+
+
+# ===========================================================================
+# PR #10 review fixes (data URI, image_paths cwd, click.UsageError)
+# ===========================================================================
+
+
+def test_pr10_review_data_uri_no_leading_space():
+    """PR #10 review fix. RFC 2397 says no whitespace after the
+    ``base64,`` separator in data URIs."""
+    from wireviz.svgembed import data_URI_base64
+    import tempfile, os
+
+    # Write a tiny PNG to disk and base64-URI it
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+        Image.new("RGB", (4, 4), "blue").save(f, format="PNG")
+        tmp = f.name
+    try:
+        uri = data_URI_base64(tmp)
+        # Right after `base64,` should be a non-space character (the
+        # first base64 byte is alphabetic for any non-trivial PNG).
+        idx = uri.index(";base64,")
+        char_after_comma = uri[idx + len(";base64,")]
+        assert char_after_comma != " ", "data URI must not have leading space"
+    finally:
+        os.unlink(tmp)
+
+
+def test_pr10_review_unknown_format_uses_click_usage_error(runner, minimal_yaml: Path):
+    """PR #10 review fix. Unknown -f code raises click.UsageError,
+    not a generic Exception."""
+    result = runner.invoke(cli, ["-f", "X", str(minimal_yaml)])
+    assert result.exit_code == 2
+    # click.UsageError adds the canonical "Try 'wireviz -h' for help."
+    assert "Try 'wireviz -h' for help" in result.stderr
+
+
+def test_pr10_review_source_path_autofills(minimal_yaml: Path):
+    """PR #10 review fix. ``source_path`` was documented to auto-fill
+    when ``inp`` is a Path; the code now actually does it."""
+    h = parse(minimal_yaml, return_types="harness")
+    assert h.source_path is not None
+    assert Path(h.source_path).resolve() == minimal_yaml.resolve()
+
+
+def test_pr10_review_missing_input_clean_error(runner, workdir: Path):
+    """PR #10 review fix (extension). 'File does not exist' on input
+    was a generic Exception too; now click.UsageError."""
+    result = runner.invoke(cli, [str(workdir / "missing.yml")])
+    assert result.exit_code == 2
+    assert "does not exist" in result.stderr.lower()
diff --git a/tests/test_round_trip.py b/tests/test_round_trip.py
new file mode 100644
index 000000000..61106194d
--- /dev/null
+++ b/tests/test_round_trip.py
@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""Round-trip tests — render → output bytes → re-parse → identical
+result. The high-leverage scenarios are PNG-with-embedded-YAML and
+the stdin/stdout pipe."""
+
+from pathlib import Path
+
+import pytest
+
+from wireviz.Harness import read_yaml_from_png
+from wireviz.wireviz import parse
+from wireviz.wv_cli import wireviz as cli
+
+
+def test_png_yaml_round_trip_via_cli(runner, workdir: Path, minimal_yaml: Path):
+    """Render YAML → PNG-with-embedded-source → feed PNG back to CLI →
+    rendered output uses the same harness model. This is the
+    load-bearing workflow for the planned wireviz-gui."""
+    target = workdir / "orig.yml"
+    target.write_text(minimal_yaml.read_text())
+
+    # First render: produces orig.png with embedded YAML
+    result = runner.invoke(cli, ["-f", "p", str(target)])
+    assert result.exit_code == 0, result.stderr
+
+    # Second render: feed orig.png back, produce a fresh SVG
+    result2 = runner.invoke(
+        cli, ["-f", "s", "-O", "round2", str(workdir / "orig.png")]
+    )
+    assert result2.exit_code == 0, result2.stderr
+    assert "(extracted YAML)" in result2.stderr
+
+    # The re-rendered SVG should be a valid SVG referencing X1 and W1
+    svg = (workdir / "round2.svg").read_text()
+    assert "<?xml" in svg
+    assert "X1" in svg
+    assert "W1" in svg
+
+
+def test_png_yaml_round_trip_byte_identical_yaml(
+    workdir: Path, minimal_yaml: Path
+):
+    """The YAML extracted from a PNG matches the YAML that went in
+    byte-for-byte (no whitespace normalization, no comment stripping)."""
+    yaml_text = minimal_yaml.read_text()
+    parse(
+        yaml_text,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="bytes",
+    )
+    extracted = read_yaml_from_png(workdir / "bytes.png")
+    assert extracted == yaml_text
+
+
+def test_stdin_to_stdout_svg_roundtrip(runner, minimal_yaml: Path):
+    """``cat harness.yml | wireviz -f s -O - -`` produces a valid SVG
+    on stdout."""
+    yaml_text = minimal_yaml.read_text()
+    result = runner.invoke(
+        cli,
+        ["-f", "s", "-O", "-", "-"],
+        input=yaml_text,
+    )
+    assert result.exit_code == 0
+    assert result.stdout.lstrip().startswith("<?xml")
+    assert "X1" in result.stdout
+
+
+def test_stdin_to_stdout_png_roundtrip(runner, minimal_yaml: Path):
+    """Same pipeline but binary PNG output."""
+    yaml_text = minimal_yaml.read_text()
+    result = runner.invoke(
+        cli,
+        ["-f", "p", "-O", "-", "-"],
+        input=yaml_text,
+    )
+    assert result.exit_code == 0
+    out = (
+        result.stdout_bytes
+        if hasattr(result, "stdout_bytes")
+        else result.stdout.encode("latin-1")
+    )
+    assert out.startswith(b"\x89PNG\r\n")
+
+
+def test_dict_input_round_trip_via_yaml_dump(workdir: Path, minimal_yaml: Path):
+    """Pre-parsed dict input gets ``yaml.safe_dump``'d back when
+    embedded into PNG, so round-trip is still possible (via re-parse
+    of the dumped form)."""
+    import yaml as yaml_mod
+
+    data = yaml_mod.safe_load(minimal_yaml.read_text())
+    expected = yaml_mod.safe_load(minimal_yaml.read_text())  # second copy
+    parse(
+        data,
+        output_formats=("png",),
+        output_dir=workdir,
+        output_name="dict_in",
+    )
+    extracted = read_yaml_from_png(workdir / "dict_in.png")
+    assert extracted is not None
+    # Re-parsing the extracted YAML should yield the same shape as the
+    # original input (compared against a fresh load to avoid being
+    # confused by any in-place mutation of `data`).
+    re_parsed = yaml_mod.safe_load(extracted)
+    assert re_parsed == expected
+
+
+def test_dict_input_not_mutated(minimal_yaml: Path):
+    """parse() must not mutate dict inputs — programmatic callers
+    keep references to their YAML model and expect it to survive
+    rendering unchanged.
+
+    Pre-fix, the in-place expansion of the connections section
+    (turning ``[[{X1: [1,2]}, {W1: [1,2]}]]`` into
+    ``[[{X1: 1}, {X1: 2}], [{W1: 1}, {W1: 2}]]``) leaked back to
+    the caller's dict.
+    """
+    import copy
+    import yaml as yaml_mod
+
+    data = yaml_mod.safe_load(minimal_yaml.read_text())
+    snapshot = copy.deepcopy(data)
+    parse(data, return_types="harness")
+    assert data == snapshot, "parse() mutated the caller's dict"
diff --git a/tests/test_smoke.py b/tests/test_smoke.py
new file mode 100644
index 000000000..832a5661d
--- /dev/null
+++ b/tests/test_smoke.py
@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+"""Smoke tests — every output format produces a non-empty,
+format-shaped artifact on a minimal harness.
+
+These are the cheapest tests in the suite. If any of them fail, the
+WireViz CLI is unusable for that format.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from wireviz.wireviz import parse
+
+
+@pytest.mark.parametrize(
+    "fmt, ext, signature",
+    [
+        ("svg", "svg", b"<?xml"),
+        ("png", "png", b"\x89PNG\r\n"),
+        ("gv", "gv", b"graph {"),
+        ("tsv", "bom.tsv", b"Id\t"),  # BOM TSV header
+        ("html", "html", b"<!DOCTYPE html>"),
+        ("pdf", "pdf", b"%PDF-"),
+    ],
+)
+def test_each_format_renders(minimal_yaml: Path, workdir: Path, fmt, ext, signature):
+    """Every supported output format produces a file with the right
+    magic-bytes signature. Catches: missing format codes, render-path
+    regressions, broken graphviz piping."""
+    parse(
+        minimal_yaml,
+        output_formats=(fmt,),
+        output_dir=workdir,
+        output_name="out",
+        embed_yaml=False,
+    )
+    artifact = workdir / f"out.{ext}"
+    assert artifact.exists(), f"{ext} not produced"
+    head = artifact.read_bytes()[: len(signature)]
+    assert head == signature, f"unexpected {ext} signature: {head!r}"
+
+
+def test_multi_format_one_call(minimal_yaml: Path, workdir: Path):
+    """One ``parse()`` call writes every requested format atomically."""
+    parse(
+        minimal_yaml,
+        output_formats=("svg", "png", "gv", "tsv", "html", "pdf"),
+        output_dir=workdir,
+        output_name="multi",
+        embed_yaml=False,
+    )
+    for ext in ("svg", "png", "gv", "bom.tsv", "html", "pdf"):
+        assert (workdir / f"multi.{ext}").exists(), f"{ext} missing"
+
+
+def test_minimal_gv_is_valid_graphviz(minimal_yaml: Path, workdir: Path):
+    """The .gv source must parse as valid Graphviz — i.e. balanced
+    braces, well-formed graph header. We don't shell out to ``dot -c``;
+    a structural check on the source string is enough."""
+    parse(
+        minimal_yaml,
+        output_formats=("gv",),
+        output_dir=workdir,
+        output_name="m",
+        embed_yaml=False,
+    )
+    gv = (workdir / "m.gv").read_text()
+    assert gv.startswith("graph {")
+    assert gv.rstrip().endswith("}")
+    # Nodes for X1 and W1 must both appear
+    assert "X1 [label=" in gv
+    assert "W1 [label=" in gv
+
+
+def test_html_embeds_svg_inline(minimal_yaml: Path, workdir: Path):
+    """HTML output embeds the SVG inline (not a sibling-file <img>),
+    so a single .html is self-contained."""
+    parse(
+        minimal_yaml,
+        output_formats=("html",),
+        output_dir=workdir,
+        output_name="h",
+        embed_yaml=False,
+    )
+    html = (workdir / "h.html").read_text()
+    assert "<svg " in html, "HTML output should contain inline SVG"
+    assert "<!-- %diagram% -->" not in html, "diagram placeholder unresolved"
+
+
+def test_tsv_has_header_and_one_data_row(minimal_yaml: Path, workdir: Path):
+    """The BOM TSV always starts with a header row and contains at
+    least one component row for the cable in this minimal harness."""
+    parse(
+        minimal_yaml,
+        output_formats=("tsv",),
+        output_dir=workdir,
+        output_name="b",
+        embed_yaml=False,
+    )
+    rows = (workdir / "b.bom.tsv").read_text().splitlines()
+    assert len(rows) >= 2, "expected header + at least one data row"
+    # Header line: tab-separated column names starting with "Id"
+    assert rows[0].split("\t")[0] == "Id", "first row should be the column header"
+    # Cable W1 should appear in some data row
+    assert any("W1" in r or "Cable" in r for r in rows[1:])