test: add property-based tests using Hypothesis

Add PBT tests to improve edge case coverage across multiple modules:

- test_feedback.py: whitespace validation, invalid JSON patterns
- test_models.py: HTTP method case variations, JSON parsing errors,
  account ID round-trips
- test_tfidf_index.py: punctuation removal, stopword filtering,
  score range invariants, result ordering
- test_toolset.py: auth header encoding, glob pattern matching,
  provider filtering case-insensitivity
- test_meta_tools.py: score threshold filtering, limit constraints,
  hybrid alpha clamping

PBT automatically generates diverse inputs to discover bugs that
hardcoded test cases might miss, particularly in input validation
and boundary conditions.

Author: ryoppippi

tests/test_feedback.py

@@ -5,14 +5,44 @@
 
 import json
 import os
+import string
 
 import httpx
 import pytest
 import respx
+from hypothesis import given, settings
+from hypothesis import strategies as st
 
 from stackone_ai.feedback import create_feedback_tool
 from stackone_ai.models import StackOneError
 
+# Hypothesis strategies for PBT
+# Various whitespace characters including Unicode
+WHITESPACE_CHARS = " \t\n\r\u00a0\u2003\u2009"
+whitespace_strategy = st.text(alphabet=WHITESPACE_CHARS, min_size=1, max_size=20)
+
+# Valid non-empty strings (stripped)
+valid_string_strategy = st.text(
+    alphabet=string.ascii_letters + string.digits + "_-",
+    min_size=1,
+    max_size=50,
+).filter(lambda s: s.strip())
+
+# Invalid JSON strings (strings that cannot be parsed as valid JSON at all)
+# Note: Python's json module accepts NaN/Infinity by default, so avoid those
+invalid_json_strategy = st.one_of(
+    st.just("{incomplete"),
+    st.just('{"missing": }'),
+    st.just('{"key": value}'),
+    st.just("[1, 2, 3"),
+    st.just("{trailing}garbage"),
+    st.just("{missing closing brace"),
+    st.just("undefined"),
+    st.just("not valid json"),
+    st.just("abc123"),
+    st.just("foo bar baz"),
+)
+
 
 class TestFeedbackToolValidation:
     """Test suite for feedback tool input validation."""
@@ -79,6 +109,59 @@ def test_invalid_json_input(self) -> None:
         with pytest.raises(StackOneError, match="Invalid JSON"):
             tool.execute("{missing closing brace")
 
+    @given(whitespace=whitespace_strategy)
+    @settings(max_examples=50)
+    def test_whitespace_feedback_validation_pbt(self, whitespace: str) -> None:
+        """PBT: Test validation for various whitespace patterns in feedback."""
+        tool = create_feedback_tool(api_key="test_key")
+
+        with pytest.raises(StackOneError, match="non-empty"):
+            tool.execute({"feedback": whitespace, "account_id": "acc_123456", "tool_names": ["test_tool"]})
+
+    @given(whitespace=whitespace_strategy)
+    @settings(max_examples=50)
+    def test_whitespace_account_id_validation_pbt(self, whitespace: str) -> None:
+        """PBT: Test validation for various whitespace patterns in account_id."""
+        tool = create_feedback_tool(api_key="test_key")
+
+        with pytest.raises(StackOneError, match="non-empty"):
+            tool.execute({"feedback": "Great!", "account_id": whitespace, "tool_names": ["test_tool"]})
+
+    @given(whitespace_list=st.lists(whitespace_strategy, min_size=1, max_size=5))
+    @settings(max_examples=50)
+    def test_whitespace_tool_names_validation_pbt(self, whitespace_list: list[str]) -> None:
+        """PBT: Test validation for lists containing only whitespace tool names."""
+        tool = create_feedback_tool(api_key="test_key")
+
+        with pytest.raises(StackOneError, match="At least one tool name"):
+            tool.execute({"feedback": "Great!", "account_id": "acc_123456", "tool_names": whitespace_list})
+
+    @given(
+        whitespace_list=st.lists(whitespace_strategy, min_size=1, max_size=5),
+    )
+    @settings(max_examples=50)
+    def test_whitespace_account_ids_list_validation_pbt(self, whitespace_list: list[str]) -> None:
+        """PBT: Test validation for lists containing only whitespace account IDs."""
+        tool = create_feedback_tool(api_key="test_key")
+
+        with pytest.raises(StackOneError, match="At least one valid account ID is required"):
+            tool.execute(
+                {
+                    "feedback": "Great tools!",
+                    "account_id": whitespace_list,
+                    "tool_names": ["test_tool"],
+                }
+            )
+
+    @given(invalid_json=invalid_json_strategy)
+    @settings(max_examples=50)
+    def test_invalid_json_input_pbt(self, invalid_json: str) -> None:
+        """PBT: Test that various invalid JSON inputs raise appropriate error."""
+        tool = create_feedback_tool(api_key="test_key")
+
+        with pytest.raises(StackOneError, match="Invalid JSON"):
+            tool.execute(invalid_json)
+
     @respx.mock
     def test_json_string_input(self) -> None:
         """Test that JSON string input is properly parsed."""

tests/test_meta_tools.py

@@ -3,6 +3,8 @@
 import httpx
 import pytest
 import respx
+from hypothesis import given, settings
+from hypothesis import strategies as st
 
 from stackone_ai import StackOneTool, Tools
 from stackone_ai.meta_tools import (
@@ -12,6 +14,77 @@
 )
 from stackone_ai.models import ExecuteConfig, ToolParameters
 
+# Hypothesis strategies for PBT
+# Score threshold strategy
+score_threshold_strategy = st.floats(min_value=0.0, max_value=1.0, allow_nan=False, allow_infinity=False)
+
+# Hybrid alpha strategy (can be outside [0, 1] to test clamping)
+hybrid_alpha_strategy = st.floats(min_value=-10.0, max_value=10.0, allow_nan=False, allow_infinity=False)
+
+# Limit strategy
+limit_strategy = st.integers(min_value=1, max_value=100)
+
+
+def _create_sample_tools() -> list[StackOneTool]:
+    """Helper function to create sample tools (for use in PBT tests)."""
+    tools = []
+
+    # Create HiBob tools
+    for action in ["create", "list", "update", "delete"]:
+        for entity in ["employee", "department", "timeoff"]:
+            tool_name = f"hibob_{action}_{entity}"
+            execute_config = ExecuteConfig(
+                name=tool_name,
+                method="POST" if action in ["create", "update"] else "GET",
+                url=f"https://api.example.com/hibob/{entity}",
+                headers={},
+            )
+
+            parameters = ToolParameters(
+                type="object",
+                properties={
+                    "id": {"type": "string", "description": "Entity ID"},
+                    "data": {"type": "object", "description": "Entity data"},
+                },
+            )
+
+            tool = StackOneTool(
+                description=f"{action.capitalize()} {entity} in HiBob system",
+                parameters=parameters,
+                _execute_config=execute_config,
+                _api_key="test_key",
+            )
+            tools.append(tool)
+
+    # Create BambooHR tools
+    for action in ["create", "list", "search"]:
+        for entity in ["candidate", "job", "application"]:
+            tool_name = f"bamboohr_{action}_{entity}"
+            execute_config = ExecuteConfig(
+                name=tool_name,
+                method="POST" if action == "create" else "GET",
+                url=f"https://api.example.com/bamboohr/{entity}",
+                headers={},
+            )
+
+            parameters = ToolParameters(
+                type="object",
+                properties={
+                    "query": {"type": "string", "description": "Search query"},
+                    "filters": {"type": "object", "description": "Filter criteria"},
+                },
+            )
+
+            tool = StackOneTool(
+                description=f"{action.capitalize()} {entity} in BambooHR system",
+                parameters=parameters,
+                _execute_config=execute_config,
+                _api_key="test_key",
+            )
+            tools.append(tool)
+
+    return tools
+
 
 @pytest.fixture
 def sample_tools():
@@ -132,6 +205,36 @@ def test_search_limit(self, sample_tools):
 
         assert len(results) <= 3
 
+    @given(min_score=score_threshold_strategy, limit=limit_strategy)
+    @settings(max_examples=50)
+    def test_search_with_min_score_pbt(self, min_score: float, limit: int):
+        """PBT: Test that min_score filtering always works correctly."""
+        # Create tools inside test to avoid fixture issues with Hypothesis
+        tools = _create_sample_tools()
+        index = ToolIndex(tools)
+
+        results = index.search("employee", limit=limit, min_score=min_score)
+
+        # All results must meet the score threshold
+        for r in results:
+            assert r.score >= min_score, f"Score {r.score} < min_score {min_score}"
+
+        # Result count should not exceed limit
+        assert len(results) <= limit
+
+    @given(limit=limit_strategy)
+    @settings(max_examples=50)
+    def test_search_limit_pbt(self, limit: int):
+        """PBT: Test that limit is always respected."""
+        # Create tools inside test to avoid fixture issues with Hypothesis
+        tools = _create_sample_tools()
+        index = ToolIndex(tools)
+
+        results = index.search("employee", limit=limit)
+
+        assert len(results) <= limit
+        assert len(results) <= len(tools)
+
 
 class TestMetaSearchTool:
     """Test the meta_search_tools functionality"""
@@ -309,6 +412,25 @@ def test_hybrid_alpha_parameter(self, sample_tools):
         index_max = ToolIndex(sample_tools, hybrid_alpha=1.5)
         assert index_max.hybrid_alpha == 1.0
 
+    @given(alpha=hybrid_alpha_strategy)
+    @settings(max_examples=100)
+    def test_hybrid_alpha_clamping_pbt(self, alpha: float):
+        """PBT: Test that hybrid_alpha is always clamped to [0.0, 1.0]."""
+        # Create tools inside test to avoid fixture issues with Hypothesis
+        tools = _create_sample_tools()
+        index = ToolIndex(tools, hybrid_alpha=alpha)
+
+        # Should always be clamped to [0.0, 1.0]
+        assert 0.0 <= index.hybrid_alpha <= 1.0
+
+        # Verify clamping logic
+        if alpha < 0.0:
+            assert index.hybrid_alpha == 0.0
+        elif alpha > 1.0:
+            assert index.hybrid_alpha == 1.0
+        else:
+            assert index.hybrid_alpha == alpha
+
     def test_hybrid_search_returns_results(self, sample_tools):
         """Test that hybrid search returns meaningful results"""
         index = ToolIndex(sample_tools, hybrid_alpha=0.2)