kafka-viewer 0.1.0__tar.gz

kafka_viewer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shashank Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kafka_viewer-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: kafka-viewer
+Version: 0.1.0
+Summary: A lightweight local Kafka message inspection tool
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kafka-python<4,>=3.0.11
+Requires-Dist: streamlit<2,>=1.35
+Provides-Extra: test
+Requires-Dist: pytest<10,>=9.0.3; extra == "test"
+Provides-Extra: build
+Requires-Dist: build<2,>=1; extra == "build"
+Provides-Extra: security
+Requires-Dist: pip-audit<3,>=2.9; extra == "security"
+Dynamic: license-file
+
+# kafka-viewer
+
+`kafka-viewer` is a lightweight local Streamlit UI for inspecting messages in an unsecured Kafka cluster. Kafka connection details come from a local properties file, and the viewer does not commit consumer offsets.
+
+## Installation
+
+```bash
+pip install kafka-viewer
+```
+
+## Configuration
+
+Create a local properties file named `kafka-viewer.properties`:
+
+```properties
+kafka.bootstrap.servers=localhost:9092
+```
+
+The configuration remains local to your machine.
+
+## Usage
+
+The `--config` option is required:
+
+```bash
+kafka-viewer-unsecured --config /path/to/kafka-viewer.properties
+```
+
+Windows:
+
+```text
+kafka-viewer-unsecured --config C:\path\to\kafka-viewer.properties
+```
+
+The UI lets you check Kafka connection status, discover and select topics, enter or generate a temporary consumer group ID, and load:
+
+- The latest N messages.
+- Messages from the beginning.
+- Messages from a date/time.
+- Messages within a date/time range.
+
+Loaded messages show the partition, offset, timestamp, key, and message value. Messages can be expanded to view the complete message value, including formatted JSON when applicable.
+
+## V1 limitations
+
+V1 supports unsecured Kafka only. It does not support:
+
+- Kafka authentication or security configuration.
+- Avro, Schema Registry, or Protobuf.
+- Publishing messages.
+- Topic or consumer-group administration.
+- Multiple Kafka clusters.
+
+## Development
+
+```bash
+python -m pytest
+python -m build
+```

kafka_viewer-0.1.0/README.md

@@ -0,0 +1,59 @@
+# kafka-viewer
+
+`kafka-viewer` is a lightweight local Streamlit UI for inspecting messages in an unsecured Kafka cluster. Kafka connection details come from a local properties file, and the viewer does not commit consumer offsets.
+
+## Installation
+
+```bash
+pip install kafka-viewer
+```
+
+## Configuration
+
+Create a local properties file named `kafka-viewer.properties`:
+
+```properties
+kafka.bootstrap.servers=localhost:9092
+```
+
+The configuration remains local to your machine.
+
+## Usage
+
+The `--config` option is required:
+
+```bash
+kafka-viewer-unsecured --config /path/to/kafka-viewer.properties
+```
+
+Windows:
+
+```text
+kafka-viewer-unsecured --config C:\path\to\kafka-viewer.properties
+```
+
+The UI lets you check Kafka connection status, discover and select topics, enter or generate a temporary consumer group ID, and load:
+
+- The latest N messages.
+- Messages from the beginning.
+- Messages from a date/time.
+- Messages within a date/time range.
+
+Loaded messages show the partition, offset, timestamp, key, and message value. Messages can be expanded to view the complete message value, including formatted JSON when applicable.
+
+## V1 limitations
+
+V1 supports unsecured Kafka only. It does not support:
+
+- Kafka authentication or security configuration.
+- Avro, Schema Registry, or Protobuf.
+- Publishing messages.
+- Topic or consumer-group administration.
+- Multiple Kafka clusters.
+
+## Development
+
+```bash
+python -m pytest
+python -m build
+```

kafka_viewer-0.1.0/kafka_viewer/__init__.py

@@ -0,0 +1,3 @@
+"""Local Kafka message viewer."""
+
+__version__ = "0.1.0"

kafka_viewer-0.1.0/kafka_viewer/cli.py

@@ -0,0 +1,29 @@
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from .config import load_properties
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Start the unsecured Kafka viewer")
+    parser.add_argument("--config", required=True, help="Path to a properties file")
+    args = parser.parse_args()
+    config_path = Path(args.config)
+    load_properties(config_path)
+    command = [
+        sys.executable,
+        "-m",
+        "streamlit",
+        "run",
+        str(Path(__file__).with_name("ui.py")),
+        "--",
+        "--config",
+        str(config_path),
+    ]
+    raise SystemExit(subprocess.call(command))
+
+
+if __name__ == "__main__":
+    main()

kafka_viewer-0.1.0/kafka_viewer/config.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+
+class ConfigError(ValueError):
+    """Raised when the viewer configuration is invalid."""
+
+
+def load_properties(path: str | Path) -> dict[str, str]:
+    config_path = Path(path)
+    if not config_path.is_file():
+        raise FileNotFoundError(f"Configuration file not found: {config_path}")
+
+    properties: dict[str, str] = {}
+    for line_number, raw_line in enumerate(config_path.read_text(encoding="utf-8").splitlines(), 1):
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise ConfigError(f"Invalid configuration line {line_number}: expected key=value")
+        key, value = (part.strip() for part in line.split("=", 1))
+        if not key:
+            raise ConfigError(f"Invalid configuration line {line_number}: empty key")
+        properties[key] = value
+
+    bootstrap_servers = properties.get("kafka.bootstrap.servers", "").strip()
+    if not bootstrap_servers:
+        raise ConfigError("Missing required property: kafka.bootstrap.servers")
+    properties["kafka.bootstrap.servers"] = bootstrap_servers
+    return properties

kafka_viewer-0.1.0/kafka_viewer/kafka_client.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Iterable
+
+from kafka import KafkaConsumer, TopicPartition
+
+
+@dataclass(frozen=True)
+class Message:
+    partition: int
+    offset: int
+    timestamp: int | None
+    key: Any
+    value: Any
+
+
+def validate_count(value: Any) -> int:
+    try:
+        count = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("Message count must be a positive integer") from exc
+    if count <= 0:
+        raise ValueError("Message count must be a positive integer")
+    return count
+
+
+def generate_group_id() -> str:
+    return f"kafka-viewer-{uuid.uuid4().hex[:12]}"
+
+
+def _readable(value: Any) -> str:
+    if value is None:
+        return "<null>"
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return str(value)
+
+
+def format_value(value: Any) -> str:
+    if value is None:
+        return "<null>"
+    readable = _readable(value)
+    try:
+        parsed = json.loads(readable)
+    except (TypeError, json.JSONDecodeError):
+        return readable
+    return json.dumps(parsed, indent=2, ensure_ascii=False)
+
+
+def format_key(value: Any) -> str:
+    return _readable(value)
+
+
+def datetime_to_millis(value: datetime) -> int:
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return int(value.timestamp() * 1000)
+
+
+class KafkaClient:
+    def __init__(self, bootstrap_servers: str, consumer_factory: Callable[..., Any] = KafkaConsumer):
+        self.bootstrap_servers = bootstrap_servers
+        self.consumer_factory = consumer_factory
+
+    def topics(self) -> set[str]:
+        consumer = self.consumer_factory(
+            bootstrap_servers=self.bootstrap_servers,
+            request_timeout_ms=5000,
+            api_version_auto_timeout_ms=3000,
+        )
+        try:
+            return set(consumer.topics())
+        finally:
+            consumer.close()
+
+    def load_messages(
+        self,
+        topic: str,
+        group_id: str,
+        mode: str,
+        count: int,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> list[Message]:
+        count = validate_count(count)
+        if mode not in {"latest", "beginning", "from_date", "range"}:
+            raise ValueError("Unknown loading mode")
+        if mode in {"from_date", "range"} and start is None:
+            raise ValueError("A start date/time is required")
+        if mode == "range" and end is None:
+            raise ValueError("An end date/time is required")
+        if mode == "range" and datetime_to_millis(start) > datetime_to_millis(end):
+            raise ValueError("End date/time must not be before start date/time")
+
+        consumer = self.consumer_factory(
+            bootstrap_servers=self.bootstrap_servers,
+            group_id=group_id or None,
+            enable_auto_commit=False,
+            consumer_timeout_ms=1500,
+            request_timeout_ms=5000,
+        )
+        try:
+            partitions = [TopicPartition(topic, number) for number in (consumer.partitions_for_topic(topic) or set())]
+            if not partitions:
+                return []
+            end_offsets = consumer.end_offsets(partitions)
+            if mode == "latest":
+                starts = {partition: max(0, end_offsets[partition] - count) for partition in partitions}
+            elif mode == "beginning":
+                starts = consumer.beginning_offsets(partitions)
+            else:
+                starts = consumer.offsets_for_times({partition: datetime_to_millis(start) for partition in partitions})
+                starts = {partition: offset.offset for partition, offset in starts.items() if offset is not None}
+
+            active = {partition for partition, offset in starts.items() if offset < end_offsets[partition]}
+            if not active:
+                return []
+            consumer.assign(list(active))
+            for partition, offset in starts.items():
+                if partition not in active:
+                    continue
+                consumer.seek(partition, offset)
+
+            records: list[Message] = []
+            idle_polls = 0
+            while active and (mode == "latest" or len(records) < count):
+                batch = consumer.poll(timeout_ms=1000)
+                if not batch:
+                    idle_polls += 1
+                    if idle_polls >= 2:
+                        break
+                    continue
+                idle_polls = 0
+                for record in _records(batch):
+                    partition = TopicPartition(record.topic, record.partition)
+                    if record.offset >= end_offsets[partition]:
+                        continue
+                    timestamp = record.timestamp
+                    if mode == "from_date" and (timestamp is None or timestamp < datetime_to_millis(start)):
+                        continue
+                    if mode == "range" and (timestamp is None or timestamp < datetime_to_millis(start) or timestamp > datetime_to_millis(end)):
+                        if timestamp is not None and timestamp > datetime_to_millis(end):
+                            active.discard(partition)
+                        continue
+                    records.append(Message(record.partition, record.offset, timestamp, record.key, record.value))
+                    if mode == "range" and timestamp is not None and timestamp >= datetime_to_millis(end):
+                        active.discard(partition)
+                    if len(records) >= count:
+                        break
+                for partition in list(active):
+                    if consumer.position(partition) >= end_offsets[partition]:
+                        active.discard(partition)
+            records.sort(key=lambda item: (item.timestamp if item.timestamp is not None else -1, item.partition, item.offset))
+            return records[-count:]
+        finally:
+            consumer.close()
+
+
+def _records(batch: dict[Any, Iterable[Any]]) -> Iterable[Any]:
+    for records in batch.values():
+        yield from records

kafka_viewer-0.1.0/kafka_viewer/ui.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, time
+
+import streamlit as st
+
+from kafka_viewer.config import load_properties
+from kafka_viewer.kafka_client import KafkaClient, format_key, format_value, generate_group_id, validate_count
+
+
+def _config_path() -> str:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--config", default="kafka-viewer.properties")
+    return parser.parse_known_args(sys.argv[1:])[0].config
+
+
+def _date_time(label: str, key: str) -> datetime:
+    selected_date = st.date_input(label, key=f"{key}-date")
+    selected_time = st.time_input(f"{label} time", value=time(0, 0), key=f"{key}-time")
+    return datetime.combine(selected_date, selected_time)
+
+
+def main() -> None:
+    st.set_page_config(page_title="Kafka Viewer", layout="wide")
+    st.title("Kafka Viewer")
+    config_path = _config_path()
+    st.caption(f"Configuration: {config_path}")
+
+    try:
+        properties = load_properties(config_path)
+    except (OSError, ValueError) as exc:
+        st.error(str(exc))
+        return
+
+    bootstrap_servers = properties["kafka.bootstrap.servers"]
+    st.write(f"Broker: `{bootstrap_servers}`")
+    client = KafkaClient(bootstrap_servers)
+    if "connection_status" not in st.session_state:
+        st.session_state.connection_status = "Connecting"
+    if "topics" not in st.session_state:
+        st.session_state.topics = None
+        try:
+            st.session_state.topics = sorted(client.topics())
+            st.session_state.connection_status = "Connected"
+        except Exception as exc:
+            st.session_state.connection_status = "Disconnected"
+            st.session_state.connection_error = str(exc)
+
+    status = st.session_state.connection_status
+    st.subheader(f"Status: {status}")
+    if status == "Disconnected":
+        st.error(f"Kafka connection failed: {st.session_state.get('connection_error', 'unknown error')}")
+    if st.button("Test / Refresh Connection"):
+        try:
+            st.session_state.topics = sorted(client.topics())
+            st.session_state.connection_status = "Connected"
+            st.session_state.pop("connection_error", None)
+        except Exception as exc:
+            st.session_state.connection_status = "Disconnected"
+            st.session_state.connection_error = str(exc)
+        st.rerun()
+    if status != "Connected":
+        return
+
+    topics = st.session_state.get("topics") or []
+    if st.button("Refresh Topics"):
+        try:
+            st.session_state.topics = sorted(client.topics())
+        except Exception as exc:
+            st.error(f"Unable to discover topics: {exc}")
+        st.rerun()
+    if not topics:
+        st.info("No topics are available.")
+        return
+
+    topic = st.selectbox("Topic", topics)
+    group_id = st.text_input("Consumer group ID", value=st.session_state.get("group_id", ""))
+    if st.button("Generate Temporary Group ID"):
+        st.session_state.group_id = generate_group_id()
+        st.rerun()
+    group_id = st.session_state.get("group_id", group_id)
+    modes = {"Latest messages": "latest", "From beginning": "beginning", "From date/time": "from_date", "Date/time range": "range"}
+    mode_label = st.radio("Loading mode", list(modes), index=0)
+    mode = modes[mode_label]
+    start = end = None
+    if mode == "latest":
+        count = st.number_input("Message count", min_value=1, value=100, step=1)
+    elif mode == "beginning":
+        count = st.number_input("Maximum message count", min_value=1, value=100, step=1)
+    elif mode == "from_date":
+        start = _date_time("Start date", "start")
+        count = st.number_input("Maximum message count", min_value=1, value=100, step=1)
+    else:
+        start = _date_time("Start date", "range-start")
+        end = _date_time("End date", "range-end")
+        count = st.number_input("Maximum message count", min_value=1, value=100, step=1)
+
+    load_col, clear_col = st.columns(2)
+    if load_col.button("Load Messages", type="primary"):
+        try:
+            validate_count(count)
+            st.session_state.messages = client.load_messages(topic, group_id, mode, int(count), start, end)
+        except Exception as exc:
+            st.error(f"Unable to load messages: {exc}")
+    if clear_col.button("Clear Loaded Messages"):
+        st.session_state.messages = []
+
+    messages = st.session_state.get("messages", [])
+    if not messages:
+        st.info("No messages loaded.")
+        return
+    st.dataframe(
+        [{"Partition": message.partition, "Offset": message.offset, "Timestamp": message.timestamp, "Key": format_key(message.key), "Message preview": format_value(message.value)[:500]} for message in messages],
+        use_container_width=True,
+        hide_index=True,
+    )
+    st.subheader("Message details")
+    for index, message in enumerate(messages, 1):
+        with st.expander(f"#{index} partition={message.partition} offset={message.offset}"):
+            st.write({"Partition": message.partition, "Offset": message.offset, "Timestamp": message.timestamp, "Key": format_key(message.key)})
+            st.code(format_value(message.value), language="json" if format_value(message.value).lstrip().startswith(("{", "[")) else None)
+
+
+if __name__ == "__main__":
+    main()

kafka_viewer-0.1.0/kafka_viewer.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: kafka-viewer
+Version: 0.1.0
+Summary: A lightweight local Kafka message inspection tool
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: kafka-python<4,>=3.0.11
+Requires-Dist: streamlit<2,>=1.35
+Provides-Extra: test
+Requires-Dist: pytest<10,>=9.0.3; extra == "test"
+Provides-Extra: build
+Requires-Dist: build<2,>=1; extra == "build"
+Provides-Extra: security
+Requires-Dist: pip-audit<3,>=2.9; extra == "security"
+Dynamic: license-file
+
+# kafka-viewer
+
+`kafka-viewer` is a lightweight local Streamlit UI for inspecting messages in an unsecured Kafka cluster. Kafka connection details come from a local properties file, and the viewer does not commit consumer offsets.
+
+## Installation
+
+```bash
+pip install kafka-viewer
+```
+
+## Configuration
+
+Create a local properties file named `kafka-viewer.properties`:
+
+```properties
+kafka.bootstrap.servers=localhost:9092
+```
+
+The configuration remains local to your machine.
+
+## Usage
+
+The `--config` option is required:
+
+```bash
+kafka-viewer-unsecured --config /path/to/kafka-viewer.properties
+```
+
+Windows:
+
+```text
+kafka-viewer-unsecured --config C:\path\to\kafka-viewer.properties
+```
+
+The UI lets you check Kafka connection status, discover and select topics, enter or generate a temporary consumer group ID, and load:
+
+- The latest N messages.
+- Messages from the beginning.
+- Messages from a date/time.
+- Messages within a date/time range.
+
+Loaded messages show the partition, offset, timestamp, key, and message value. Messages can be expanded to view the complete message value, including formatted JSON when applicable.
+
+## V1 limitations
+
+V1 supports unsecured Kafka only. It does not support:
+
+- Kafka authentication or security configuration.
+- Avro, Schema Registry, or Protobuf.
+- Publishing messages.
+- Topic or consumer-group administration.
+- Multiple Kafka clusters.
+
+## Development
+
+```bash
+python -m pytest
+python -m build
+```

kafka_viewer-0.1.0/kafka_viewer.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+kafka_viewer/__init__.py
+kafka_viewer/cli.py
+kafka_viewer/config.py
+kafka_viewer/kafka_client.py
+kafka_viewer/ui.py
+kafka_viewer.egg-info/PKG-INFO
+kafka_viewer.egg-info/SOURCES.txt
+kafka_viewer.egg-info/dependency_links.txt
+kafka_viewer.egg-info/entry_points.txt
+kafka_viewer.egg-info/requires.txt
+kafka_viewer.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_config.py
+tests/test_kafka_client.py

kafka_viewer-0.1.0/kafka_viewer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kafka_viewer-0.1.0/kafka_viewer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kafka-viewer-unsecured = kafka_viewer.cli:main

kafka_viewer-0.1.0/kafka_viewer.egg-info/requires.txt

@@ -0,0 +1,11 @@
+kafka-python<4,>=3.0.11
+streamlit<2,>=1.35
+
+[build]
+build<2,>=1
+
+[security]
+pip-audit<3,>=2.9
+
+[test]
+pytest<10,>=9.0.3

kafka_viewer-0.1.0/kafka_viewer.egg-info/top_level.txt

@@ -0,0 +1 @@
+kafka_viewer

kafka_viewer-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kafka-viewer"
+version = "0.1.0"
+description = "A lightweight local Kafka message inspection tool"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "kafka-python>=3.0.11,<4",
+    "streamlit>=1.35,<2",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=9.0.3,<10"]
+build = ["build>=1,<2"]
+security = ["pip-audit>=2.9,<3"]
+
+[project.scripts]
+kafka-viewer-unsecured = "kafka_viewer.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["kafka_viewer*"]

kafka_viewer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kafka_viewer-0.1.0/tests/test_cli.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+import pytest
+
+from kafka_viewer import cli
+
+
+def test_cli_requires_config_option(monkeypatch, capsys):
+    monkeypatch.setattr("sys.argv", ["kafka-viewer-unsecured"])
+
+    with pytest.raises(SystemExit) as result:
+        cli.main()
+
+    assert result.value.code == 2
+    assert "the following arguments are required: --config" in capsys.readouterr().err
+
+
+def test_cli_fails_before_starting_ui_for_missing_config_file(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(cli.subprocess, "call", lambda command: pytest.fail("UI should not start"))
+    monkeypatch.setattr("sys.argv", ["kafka-viewer-unsecured", "--config", "missing.properties"])
+
+    with pytest.raises(FileNotFoundError, match="not found"):
+        cli.main()
+
+
+def test_cli_passes_config_to_streamlit(tmp_path, monkeypatch):
+    config = tmp_path / "viewer.properties"
+    config.write_text("kafka.bootstrap.servers=broker:9092\n", encoding="utf-8")
+    calls = []
+    monkeypatch.setattr(cli.subprocess, "call", lambda command: calls.append(command) or 0)
+    monkeypatch.setattr("sys.argv", ["kafka-viewer-unsecured", "--config", str(config)])
+
+    with pytest.raises(SystemExit) as result:
+        cli.main()
+
+    assert result.value.code == 0
+    assert calls and calls[0][-1] == str(config)

kafka_viewer-0.1.0/tests/test_config.py

@@ -0,0 +1,31 @@
+import pytest
+
+from kafka_viewer.config import ConfigError, load_properties
+
+
+def test_load_properties_trims_and_ignores_comments(tmp_path):
+    path = tmp_path / "viewer.properties"
+    path.write_text("\n # comment\n kafka.bootstrap.servers = broker:9092 \n", encoding="utf-8")
+
+    assert load_properties(path) == {"kafka.bootstrap.servers": "broker:9092"}
+
+
+def test_load_properties_requires_bootstrap_servers(tmp_path):
+    path = tmp_path / "viewer.properties"
+    path.write_text("other=value\n", encoding="utf-8")
+
+    with pytest.raises(ConfigError, match="kafka.bootstrap.servers"):
+        load_properties(path)
+
+
+def test_load_properties_reports_missing_file(tmp_path):
+    with pytest.raises(FileNotFoundError, match="not found"):
+        load_properties(tmp_path / "missing.properties")
+
+
+def test_load_properties_rejects_malformed_line(tmp_path):
+    path = tmp_path / "viewer.properties"
+    path.write_text("not-a-property\n", encoding="utf-8")
+
+    with pytest.raises(ConfigError, match="key=value"):
+        load_properties(path)

kafka_viewer-0.1.0/tests/test_kafka_client.py

@@ -0,0 +1,130 @@
+from datetime import datetime, timezone
+
+import pytest
+from kafka import TopicPartition
+
+from kafka_viewer.kafka_client import (
+    KafkaClient,
+    format_value,
+    generate_group_id,
+    validate_count,
+)
+
+
+class Record:
+    def __init__(self, topic, partition, offset, timestamp, key, value):
+        self.topic = topic
+        self.partition = partition
+        self.offset = offset
+        self.timestamp = timestamp
+        self.key = key
+        self.value = value
+
+
+class Offset:
+    def __init__(self, offset):
+        self.offset = offset
+
+
+class FakeConsumer:
+    records = {
+        TopicPartition("events", 0): [Record("events", 0, 0, 1000, None, b'{"a":1}'), Record("events", 0, 1, 3000, b"k", b"last-0")],
+        TopicPartition("events", 1): [Record("events", 1, 0, 2000, b"k", b"last-1")],
+    }
+    instances = []
+
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+        self.assigned = []
+        self.positions = {}
+        self.closed = False
+        FakeConsumer.instances.append(self)
+
+    def partitions_for_topic(self, topic):
+        return {0, 1}
+
+    def end_offsets(self, partitions):
+        return {partition: len(self.records[partition]) for partition in partitions}
+
+    def beginning_offsets(self, partitions):
+        return {partition: 0 for partition in partitions}
+
+    def offsets_for_times(self, requested):
+        return {partition: Offset(0) for partition in requested}
+
+    def assign(self, partitions):
+        self.assigned = partitions
+
+    def seek(self, partition, offset):
+        self.positions[partition] = offset
+
+    def poll(self, timeout_ms):
+        batch = {}
+        for partition in self.assigned:
+            position = self.positions[partition]
+            records = [record for record in self.records[partition] if record.offset >= position]
+            if records:
+                record = records[0]
+                self.positions[partition] = record.offset + 1
+                batch[partition] = [record]
+        return batch
+
+    def position(self, partition):
+        return self.positions[partition]
+
+    def close(self):
+        self.closed = True
+
+    def topics(self):
+        return {"events"}
+
+
+def setup_function():
+    FakeConsumer.instances.clear()
+
+
+def test_latest_reads_count_total_across_partitions():
+    messages = KafkaClient("broker:9092", FakeConsumer).load_messages("events", "group", "latest", 2)
+
+    assert [(message.partition, message.offset) for message in messages] == [(1, 0), (0, 1)]
+    assert FakeConsumer.instances[-1].kwargs["enable_auto_commit"] is False
+    assert FakeConsumer.instances[-1].closed is True
+
+
+def test_from_beginning_is_bounded():
+    messages = KafkaClient("broker:9092", FakeConsumer).load_messages("events", "group", "beginning", 2)
+
+    assert len(messages) == 2
+
+
+def test_date_range_filters_record_timestamps():
+    messages = KafkaClient("broker:9092", FakeConsumer).load_messages(
+        "events",
+        "group",
+        "range",
+        10,
+        datetime.fromtimestamp(1.5, timezone.utc),
+        datetime.fromtimestamp(2.5, timezone.utc),
+    )
+
+    assert [(message.partition, message.offset) for message in messages] == [(1, 0)]
+
+
+def test_format_value_json_and_fallback():
+    assert format_value(b'{"name":"Ada"}') == '{\n  "name": "Ada"\n}'
+    assert format_value(b"plain text") == "plain text"
+    assert format_value(None) == "<null>"
+
+
+def test_group_id_is_recognizable():
+    assert generate_group_id().startswith("kafka-viewer-")
+
+
+@pytest.mark.parametrize("value", [0, -1, "nope"])
+def test_validate_count_rejects_invalid_values(value):
+    with pytest.raises(ValueError, match="positive integer"):
+        validate_count(value)
+
+
+def test_validate_count_accepts_positive_integer():
+    assert validate_count("3") == 3