db-test-helpers 0.1.0__tar.gz

db_test_helpers-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.env.test

db_test_helpers-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: db-test-helpers
+Version: 0.1.0
+Summary: YAML-driven database test data setup and verification helpers
+Project-URL: Homepage, https://github.com/takaaa220/db-test-helpers
+Project-URL: Repository, https://github.com/takaaa220/db-test-helpers
+Project-URL: Issues, https://github.com/takaaa220/db-test-helpers/issues
+Author: takaaa220
+License-Expression: MIT
+Keywords: database,fixtures,test-helpers,testing,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# db-test-helpers
+
+YAML-driven database test data setup and verification helpers. The core is DB-agnostic; DB-specific operations are handled by adapters.
+
+## Installation
+
+```bash
+pip install db-test-helpers
+```
+
+## Documentation
+
+See the [main repository](https://github.com/takaaa220/db-test-helpers) for usage and documentation.

db_test_helpers-0.1.0/README.md

@@ -0,0 +1,13 @@
+# db-test-helpers
+
+YAML-driven database test data setup and verification helpers. The core is DB-agnostic; DB-specific operations are handled by adapters.
+
+## Installation
+
+```bash
+pip install db-test-helpers
+```
+
+## Documentation
+
+See the [main repository](https://github.com/takaaa220/db-test-helpers) for usage and documentation.

db_test_helpers-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "db-test-helpers"
+version = "0.1.0"
+description = "YAML-driven database test data setup and verification helpers"
+license = "MIT"
+readme = "README.md"
+authors = [{ name = "takaaa220" }]
+keywords = ["testing", "database", "yaml", "test-helpers", "fixtures"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/takaaa220/db-test-helpers"
+Repository = "https://github.com/takaaa220/db-test-helpers"
+Issues = "https://github.com/takaaa220/db-test-helpers/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/db_test_helpers/core"]
+sources = ["src"]

db_test_helpers-0.1.0/src/db_test_helpers/core/__init__.py

@@ -0,0 +1,8 @@
+"""db-test-helpers: DB-agnostic test data helpers."""
+
+from db_test_helpers.core._errors import UnsupportedError
+from db_test_helpers.core._set import set_db_data
+from db_test_helpers.core._types import Config, DatabaseAdapter, HierarchicalAdapter
+from db_test_helpers.core._verify import verify_db_data
+
+__all__ = ["Config", "DatabaseAdapter", "HierarchicalAdapter", "UnsupportedError", "set_db_data", "verify_db_data"]

db_test_helpers-0.1.0/src/db_test_helpers/core/_errors.py

@@ -0,0 +1,5 @@
+"""Custom exceptions for db-test-helpers."""
+
+
+class UnsupportedError(Exception):
+    """Raised when an adapter does not support a requested feature."""

db_test_helpers-0.1.0/src/db_test_helpers/core/_integration_test.py

@@ -0,0 +1,164 @@
+"""Integration tests using YAML fixture files with a mock in-memory adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from db_test_helpers.core import Config, set_db_data, verify_db_data
+
+FIXTURES_DIR = str(Path(__file__).parent / "fixtures")
+
+
+class InMemoryAdapter:
+    """In-memory adapter that stores records keyed by collection path."""
+
+    def __init__(self):
+        self._store: dict[str, list[dict[str, Any]]] = {}
+        self._auto_id_counter = 0
+
+    def clear_group(self, group: str, parent_path: str) -> None:
+        col_path = f"{parent_path}/{group}" if parent_path else group
+        # Clear all entries that start with col_path (recursive)
+        keys_to_delete = [k for k in self._store if k == col_path or k.startswith(col_path + "/")]
+        for k in keys_to_delete:
+            del self._store[k]
+
+    def write_record(self, group: str, parent_path: str, data: dict[str, Any]) -> dict[str, Any]:
+        col_path = f"{parent_path}/{group}" if parent_path else group
+        data = dict(data)
+        doc_id = data.pop("__document_id__", None)
+        if doc_id is None:
+            self._auto_id_counter += 1
+            doc_id = f"auto-{self._auto_id_counter}"
+        record = {"__document_id__": doc_id, **data}
+        self._store.setdefault(col_path, []).append(record)
+        return record
+
+    def read_records(self, group: str, parent_path: str) -> list[dict[str, Any]]:
+        col_path = f"{parent_path}/{group}" if parent_path else group
+        return list(self._store.get(col_path, []))
+
+    def build_child_path(self, parent_path: str, group: str, record: dict[str, Any]) -> str:
+        col_path = f"{parent_path}/{group}" if parent_path else group
+        return f"{col_path}/{record['__document_id__']}"
+
+
+def _fixture(name: str) -> str:
+    return f"{FIXTURES_DIR}/{name}"
+
+
+class TestIntegrationBasic:
+    def test_set_and_verify_basic(self):
+        """seed_basic.yaml -> expected_basic.yaml (different order, nested dict/list)"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_basic.yaml"))
+        verify_db_data(adapter, _fixture("expected_basic.yaml"))
+
+    def test_set_clears_existing_data(self):
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_basic.yaml"))
+        # Second set should clear existing data
+        set_db_data(adapter, _fixture("seed_basic.yaml"))
+        records = adapter.read_records("users", "")
+        assert len(records) == 2
+
+
+class TestIntegrationVar:
+    def test_set_and_verify_with_var(self):
+        """$var() expansion and verification"""
+        adapter = InMemoryAdapter()
+        config = Config(variables={"uid": "test-user-123", "username": "Alice"})
+        set_db_data(adapter, _fixture("seed_with_var.yaml"), config)
+        verify_db_data(adapter, _fixture("expected_with_var.yaml"), config)
+
+    def test_var_expansion_actually_stored(self):
+        """$var() should be expanded to the actual value when stored"""
+        adapter = InMemoryAdapter()
+        config = Config(variables={"uid": "test-user-123", "username": "Alice"})
+        set_db_data(adapter, _fixture("seed_with_var.yaml"), config)
+        records = adapter.read_records("users", "")
+        assert len(records) == 1
+        assert records[0]["__document_id__"] == "test-user-123"
+        assert records[0]["name"] == "Alice"
+
+
+class TestIntegrationAny:
+    def test_set_and_verify_with_any(self):
+        """Omitted __document_id__ gets auto ID + verify with $any() wildcard"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_with_any.yaml"))
+        verify_db_data(adapter, _fixture("expected_with_any.yaml"))
+
+    def test_omitted_id_generates_auto_id(self):
+        """Omitting __document_id__ should make the adapter generate an auto ID"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_with_any.yaml"))
+        records = adapter.read_records("users", "")
+        assert len(records) == 2
+        for r in records:
+            assert r["__document_id__"].startswith("auto-")
+
+
+class TestIntegrationChildren:
+    def test_set_and_verify_children(self):
+        """Recursive set + verify of __children__ (multi-level, different order)"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_children.yaml"))
+        verify_db_data(adapter, _fixture("expected_children.yaml"))
+
+    def test_children_data_structure(self):
+        """__children__ data should be stored at the correct paths"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_children.yaml"))
+
+        users = adapter.read_records("users", "")
+        assert len(users) == 1
+        assert users[0]["name"] == "Alice"
+
+        posts = adapter.read_records("posts", "users/user-1")
+        assert len(posts) == 2
+
+        comments = adapter.read_records("comments", "users/user-1/posts/post-1")
+        assert len(comments) == 2
+
+
+class TestIntegrationMatchers:
+    def test_verify_with_matchers(self):
+        """seed_basic -> expected_with_matchers (verify using DSL matchers)"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_basic.yaml"))
+        verify_db_data(adapter, _fixture("expected_with_matchers.yaml"))
+
+    def test_verify_failure_with_wrong_expected(self, tmp_path):
+        """Verification should fail with wrong expected data"""
+        adapter = InMemoryAdapter()
+        set_db_data(adapter, _fixture("seed_basic.yaml"))
+
+        wrong = tmp_path / "wrong.yaml"
+        wrong.write_text(
+            """\
+users:
+  - __document_id__: "user-1"
+    name: "Charlie"
+    age: 30
+    tags:
+      - "admin"
+      - "user"
+    profile:
+      city: "Tokyo"
+      zip: "100-0001"
+  - __document_id__: "user-2"
+    name: "Bob"
+    age: 25
+    tags:
+      - "user"
+    profile:
+      city: "Osaka"
+      zip: "530-0001"
+"""
+        )
+        with pytest.raises(AssertionError):
+            verify_db_data(adapter, str(wrong))

db_test_helpers-0.1.0/src/db_test_helpers/core/_matcher_types.py

@@ -0,0 +1,69 @@
+"""Matcher Protocol and implementations."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Matcher(Protocol):
+    def matches(self, value: object) -> bool: ...
+
+
+class AnyMatcher:
+    def matches(self, value: object) -> bool:
+        return True
+
+
+class EqMatcher:
+    def __init__(self, expected: object) -> None:
+        self._expected = expected
+
+    def matches(self, value: object) -> bool:
+        if type(value) is not type(self._expected):
+            return False
+        return value == self._expected
+
+
+class LtMatcher:
+    def __init__(self, threshold: int | float) -> None:
+        self._threshold = threshold
+
+    def matches(self, value: object) -> bool:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            return False
+        return value < self._threshold
+
+
+class GtMatcher:
+    def __init__(self, threshold: int | float) -> None:
+        self._threshold = threshold
+
+    def matches(self, value: object) -> bool:
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            return False
+        return value > self._threshold
+
+
+class NotMatcher:
+    def __init__(self, inner: Matcher) -> None:
+        self._inner = inner
+
+    def matches(self, value: object) -> bool:
+        return not self._inner.matches(value)
+
+
+class AndMatcher:
+    def __init__(self, matchers: list[Matcher]) -> None:
+        self._matchers = matchers
+
+    def matches(self, value: object) -> bool:
+        return all(m.matches(value) for m in self._matchers)
+
+
+class OrMatcher:
+    def __init__(self, matchers: list[Matcher]) -> None:
+        self._matchers = matchers
+
+    def matches(self, value: object) -> bool:
+        return any(m.matches(value) for m in self._matchers)

db_test_helpers-0.1.0/src/db_test_helpers/core/_matchers.py

@@ -0,0 +1,61 @@
+"""Matcher DSL: public API facade."""
+
+from __future__ import annotations
+
+import re
+
+from db_test_helpers.core._matcher_types import (
+    AndMatcher,
+    AnyMatcher,
+    EqMatcher,
+    GtMatcher,
+    LtMatcher,
+    Matcher,
+    NotMatcher,
+    OrMatcher,
+)
+from db_test_helpers.core._parser import parse
+
+__all__ = [
+    "AndMatcher",
+    "AnyMatcher",
+    "EqMatcher",
+    "GtMatcher",
+    "LtMatcher",
+    "Matcher",
+    "NotMatcher",
+    "OrMatcher",
+    "is_dsl_string",
+    "is_var_dsl",
+    "parse_matcher",
+    "resolve_var",
+]
+
+_DSL_PATTERN = re.compile(r"^\$([a-z]+)\(")
+_VAR_PATTERN = re.compile(r"^\$var\(([^)]+)\)$")
+
+
+def is_dsl_string(value: object) -> bool:
+    if not isinstance(value, str):
+        return False
+    return _DSL_PATTERN.match(value) is not None
+
+
+def is_var_dsl(value: object) -> bool:
+    if not isinstance(value, str):
+        return False
+    return _VAR_PATTERN.match(value) is not None
+
+
+def resolve_var(value: str, variables: dict[str, object]) -> object:
+    m = _VAR_PATTERN.match(value)
+    if m is None:
+        raise ValueError(f"Not a $var() expression: {value!r}")
+    name = m.group(1).strip()
+    if name not in variables:
+        raise ValueError(f"Undefined variable: {name!r}")
+    return variables[name]
+
+
+def parse_matcher(value: str, variables: dict[str, object]) -> Matcher:
+    return parse(value, variables)

db_test_helpers-0.1.0/src/db_test_helpers/core/_matchers_test.py

@@ -0,0 +1,146 @@
+"""Tests for _matchers module."""
+
+from __future__ import annotations
+
+import pytest
+
+from db_test_helpers.core._matchers import (
+    AnyMatcher,
+    AndMatcher,
+    EqMatcher,
+    GtMatcher,
+    LtMatcher,
+    NotMatcher,
+    OrMatcher,
+    is_dsl_string,
+    is_var_dsl,
+    resolve_var,
+)
+
+
+# --- is_dsl_string ---
+
+
+class TestIsDslString:
+    def test_valid_dsl(self):
+        assert is_dsl_string("$eq(hello)") is True
+        assert is_dsl_string("$lt(100)") is True
+        assert is_dsl_string("$gt(0)") is True
+        assert is_dsl_string("$not($eq(x))") is True
+        assert is_dsl_string("$and($gt(0),$lt(10))") is True
+        assert is_dsl_string("$or($eq(a),$eq(b))") is True
+        assert is_dsl_string("$var(uid)") is True
+        assert is_dsl_string("$any()") is True
+
+    def test_unknown_dsl_function(self):
+        assert is_dsl_string("$unknown(x)") is True
+        assert is_dsl_string("$foo(bar)") is True
+
+    def test_non_dsl_string(self):
+        assert is_dsl_string("hello") is False
+        assert is_dsl_string("") is False
+
+    def test_non_string(self):
+        assert is_dsl_string(123) is False
+        assert is_dsl_string(None) is False
+        assert is_dsl_string(True) is False
+
+
+# --- is_var_dsl ---
+
+
+class TestIsVarDsl:
+    def test_var(self):
+        assert is_var_dsl("$var(uid)") is True
+
+    def test_not_var(self):
+        assert is_var_dsl("$eq(x)") is False
+        assert is_var_dsl("$any()") is False
+        assert is_var_dsl("hello") is False
+        assert is_var_dsl(123) is False
+
+
+# --- Matchers ---
+
+
+class TestAnyMatcher:
+    def test_matches_anything(self):
+        m = AnyMatcher()
+        assert m.matches("hello") is True
+        assert m.matches(123) is True
+        assert m.matches(None) is True
+        assert m.matches(True) is True
+        assert m.matches([1, 2]) is True
+        assert m.matches({"a": 1}) is True
+
+
+class TestEqMatcher:
+    def test_matches_same_type_and_value(self):
+        assert EqMatcher("hello").matches("hello") is True
+        assert EqMatcher(42).matches(42) is True
+
+    def test_rejects_different_value(self):
+        assert EqMatcher("hello").matches("world") is False
+
+    def test_rejects_different_type(self):
+        assert EqMatcher(1).matches(1.0) is False
+        assert EqMatcher("1").matches(1) is False
+
+
+class TestLtMatcher:
+    def test_less_than(self):
+        assert LtMatcher(100).matches(50) is True
+        assert LtMatcher(100).matches(100) is False
+        assert LtMatcher(100).matches(150) is False
+
+    def test_rejects_non_number(self):
+        assert LtMatcher(100).matches("50") is False
+        assert LtMatcher(100).matches(True) is False
+
+
+class TestGtMatcher:
+    def test_greater_than(self):
+        assert GtMatcher(0).matches(1) is True
+        assert GtMatcher(0).matches(0) is False
+        assert GtMatcher(0).matches(-1) is False
+
+    def test_rejects_non_number(self):
+        assert GtMatcher(0).matches("1") is False
+        assert GtMatcher(0).matches(False) is False
+
+
+class TestNotMatcher:
+    def test_negates_inner(self):
+        assert NotMatcher(EqMatcher("admin")).matches("user") is True
+        assert NotMatcher(EqMatcher("admin")).matches("admin") is False
+
+
+class TestAndMatcher:
+    def test_all_must_match(self):
+        m = AndMatcher([GtMatcher(0), LtMatcher(100)])
+        assert m.matches(50) is True
+        assert m.matches(0) is False
+        assert m.matches(100) is False
+
+
+class TestOrMatcher:
+    def test_any_must_match(self):
+        m = OrMatcher([EqMatcher("active"), EqMatcher("pending")])
+        assert m.matches("active") is True
+        assert m.matches("pending") is True
+        assert m.matches("deleted") is False
+
+
+# --- resolve_var ---
+
+
+class TestResolveVar:
+    def test_resolves_var(self):
+        assert resolve_var("$var(uid)", {"uid": "abc-123"}) == "abc-123"
+
+    def test_non_string_variable(self):
+        assert resolve_var("$var(count)", {"count": 42}) == 42
+
+    def test_undefined_variable_raises(self):
+        with pytest.raises(ValueError, match="Undefined variable"):
+            resolve_var("$var(missing)", {})

db_test_helpers-0.1.0/src/db_test_helpers/core/_parse.py

@@ -0,0 +1,73 @@
+"""YAML parser with __children__ separation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class ParsedRecord:
+    fields: dict[str, Any]
+    children: dict[str, list[ParsedRecord]] | None
+
+
+@dataclass
+class ParsedGroup:
+    name: str
+    records: list[ParsedRecord]
+
+
+def parse_yaml(filepath: str | Path) -> list[ParsedGroup]:
+    """Parse a YAML fixture file into a list of groups.
+
+    The YAML top-level must be a dict mapping group names to lists of
+    records.  The reserved key ``__children__`` is separated from
+    regular fields and stored in ``ParsedRecord.children``.
+
+    Args:
+        filepath: Path to the YAML fixture file.
+
+    Raises:
+        ValueError: If the file is empty, not a dict, or has invalid
+            structure.
+    """
+    with open(filepath) as f:
+        data = yaml.safe_load(f)
+
+    if data is None:
+        raise ValueError("YAML file is empty")
+    if not isinstance(data, dict):
+        raise ValueError(f"YAML top-level must be a dict, got {type(data).__name__}")
+
+    groups: list[ParsedGroup] = []
+    for group_name, records_data in data.items():
+        if not isinstance(records_data, list):
+            raise ValueError(f"Group '{group_name}' must be a list, got {type(records_data).__name__}")
+        records = [_parse_record(group_name, i, r) for i, r in enumerate(records_data)]
+        groups.append(ParsedGroup(name=group_name, records=records))
+
+    return groups
+
+
+def _parse_record(group_name: str, index: int, data: Any) -> ParsedRecord:
+    if not isinstance(data, dict):
+        raise ValueError(f"Record {group_name}[{index}] must be a dict, got {type(data).__name__}")
+
+    children_raw = data.get("__children__")
+    fields = {k: v for k, v in data.items() if k != "__children__"}
+
+    children: dict[str, list[ParsedRecord]] | None = None
+    if children_raw is not None:
+        if not isinstance(children_raw, dict):
+            raise ValueError(
+                f"Record {group_name}[{index}].__children__ must be a dict, got {type(children_raw).__name__}"
+            )
+        children = {}
+        for child_group, child_records in children_raw.items():
+            children[child_group] = [_parse_record(child_group, i, r) for i, r in enumerate(child_records)]
+
+    return ParsedRecord(fields=fields, children=children)