{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"dataverse-python-testing-debugging","version":"0.1.0"},"spec":{"agents_md":"---\napplyTo: '**'\n---\n\n# Dataverse SDK for Python — Testing \u0026 Debugging Strategies\n\nBased on official Azure Functions and pytest testing patterns.\n\n## 1. Testing Overview\n\n### Testing Pyramid for Dataverse SDK\n\n```\n         Integration Tests  \u003c- Test with real Dataverse\n              /\\\n             /  \\\n            /Unit Tests (Mocked)\\\n           /____________________\\\n          \u003c Framework Tests\n```\n\n---\n\n## 2. Unit Testing with Mocking\n\n### Setup Test Environment\n\n```bash\n# Install test dependencies\npip install pytest pytest-cov unittest-mock\n```\n\n### Mock DataverseClient\n\n```python\n# tests/test_operations.py\nimport pytest\nfrom unittest.mock import Mock, patch, MagicMock\nfrom PowerPlatform.Dataverse.client import DataverseClient\n\n@pytest.fixture\ndef mock_client():\n    \"\"\"Provide mocked DataverseClient.\"\"\"\n    client = Mock(spec=DataverseClient)\n    return client\n\ndef test_create_account(mock_client):\n    \"\"\"Test account creation with mocked client.\"\"\"\n    \n    # Setup mock response\n    mock_client.create.return_value = [\"id-123\"]\n    \n    # Call function\n    from my_app import create_account\n    result = create_account(mock_client, {\"name\": \"Acme\"})\n    \n    # Verify\n    assert result == \"id-123\"\n    mock_client.create.assert_called_once_with(\"account\", {\"name\": \"Acme\"})\n\ndef test_create_account_error(mock_client):\n    \"\"\"Test error handling in account creation.\"\"\"\n    from PowerPlatform.Dataverse.core.errors import DataverseError\n    \n    # Setup mock to raise error\n    mock_client.create.side_effect = DataverseError(\n        message=\"Account exists\",\n        code=\"validation_error\",\n        status_code=400\n    )\n    \n    # Verify error is raised\n    from my_app import create_account\n    with pytest.raises(DataverseError):\n        create_account(mock_client, {\"name\": \"Acme\"})\n```\n\n### Test Data Structures\n\n```python\n# tests/fixtures.py\nimport pytest\n\n@pytest.fixture\ndef sample_account():\n    \"\"\"Sample account record for testing.\"\"\"\n    return {\n        \"accountid\": \"id-123\",\n        \"name\": \"Acme Inc\",\n        \"telephone1\": \"555-0100\",\n        \"statecode\": 0,\n        \"createdon\": \"2025-01-01T00:00:00Z\"\n    }\n\n@pytest.fixture\ndef sample_accounts(sample_account):\n    \"\"\"Multiple sample accounts.\"\"\"\n    return [\n        sample_account,\n        {**sample_account, \"accountid\": \"id-124\", \"name\": \"Fabrikam\"},\n        {**sample_account, \"accountid\": \"id-125\", \"name\": \"Contoso\"},\n    ]\n\n# Usage in tests\ndef test_process_accounts(mock_client, sample_accounts):\n    mock_client.get.return_value = iter([sample_accounts])\n    # Test processing\n```\n\n---\n\n## 3. Mocking Common Patterns\n\n### Mock Get with Pagination\n\n```python\ndef test_pagination(mock_client, sample_accounts):\n    \"\"\"Test handling paginated results.\"\"\"\n    \n    # Mock returns generator with pages\n    mock_client.get.return_value = iter([\n        sample_accounts[:2],  # Page 1\n        sample_accounts[2:]   # Page 2\n    ])\n    \n    from my_app import process_all_accounts\n    result = process_all_accounts(mock_client)\n    \n    assert len(result) == 3  # All pages processed\n```\n\n### Mock Bulk Operations\n\n```python\ndef test_bulk_create(mock_client):\n    \"\"\"Test bulk account creation.\"\"\"\n    \n    payloads = [\n        {\"name\": \"Account 1\"},\n        {\"name\": \"Account 2\"},\n    ]\n    \n    # Mock returns list of IDs\n    mock_client.create.return_value = [\"id-1\", \"id-2\"]\n    \n    from my_app import create_accounts\n    ids = create_accounts(mock_client, payloads)\n    \n    assert len(ids) == 2\n    mock_client.create.assert_called_once_with(\"account\", payloads)\n```\n\n### Mock Errors\n\n```python\ndef test_rate_limiting_retry(mock_client):\n    \"\"\"Test retry logic on rate limiting.\"\"\"\n    from PowerPlatform.Dataverse.core.errors import DataverseError\n    \n    # Mock fails then succeeds\n    error = DataverseError(\n        message=\"Too many requests\",\n        code=\"http_error\",\n        status_code=429,\n        is_transient=True\n    )\n    mock_client.create.side_effect = [error, [\"id-123\"]]\n    \n    from my_app import create_with_retry\n    result = create_with_retry(mock_client, \"account\", {})\n    \n    assert result == \"id-123\"\n    assert mock_client.create.call_count == 2  # Retried\n```\n\n---\n\n## 4. Integration Testing\n\n### Local Development Testing\n\n```python\n# tests/test_integration.py\nimport pytest\nfrom azure.identity import InteractiveBrowserCredential\nfrom PowerPlatform.Dataverse.client import DataverseClient\n\n@pytest.fixture\ndef dataverse_client():\n    \"\"\"Real client for integration testing.\"\"\"\n    client = DataverseClient(\n        base_url=\"https://myorg-dev.crm.dynamics.com\",\n        credential=InteractiveBrowserCredential()\n    )\n    return client\n\n@pytest.mark.integration\ndef test_create_and_retrieve_account(dataverse_client):\n    \"\"\"Test creating and retrieving account (against real Dataverse).\"\"\"\n    \n    # Create\n    account_id = dataverse_client.create(\"account\", {\n        \"name\": \"Test Account\"\n    })[0]\n    \n    # Retrieve\n    account = dataverse_client.get(\"account\", account_id)\n    \n    # Verify\n    assert account[\"name\"] == \"Test Account\"\n    \n    # Cleanup\n    dataverse_client.delete(\"account\", account_id)\n```\n\n### Test Isolation\n\n```python\n# tests/conftest.py\nimport pytest\n\n@pytest.fixture(scope=\"function\")\ndef test_account(dataverse_client):\n    \"\"\"Create test account, cleanup after test.\"\"\"\n    \n    account_id = dataverse_client.create(\"account\", {\n        \"name\": \"Test Account\"\n    })[0]\n    \n    yield account_id\n    \n    # Cleanup\n    try:\n        dataverse_client.delete(\"account\", account_id)\n    except:\n        pass  # Already deleted\n\n# Usage\ndef test_update_account(dataverse_client, test_account):\n    \"\"\"Test updating account.\"\"\"\n    dataverse_client.update(\"account\", test_account, {\"telephone1\": \"555-0100\"})\n    \n    account = dataverse_client.get(\"account\", test_account)\n    assert account[\"telephone1\"] == \"555-0100\"\n```\n\n---\n\n## 5. Pytest Configuration\n\n### pytest.ini\n\n```ini\n[pytest]\n# Skip integration tests by default\ntestpaths = tests\npython_files = test_*.py\npython_classes = Test*\npython_functions = test_*\n\nmarkers =\n    integration: marks tests as integration (run with -m integration)\n    slow: marks tests as slow\n    unit: marks tests as unit tests\n```\n\n### Run Tests\n\n```bash\n# Unit tests only\npytest\n\n# Unit + integration\npytest -m \"unit or integration\"\n\n# Integration only\npytest -m integration\n\n# With coverage\npytest --cov=my_app tests/\n\n# Specific test\npytest tests/test_operations.py::test_create_account\n```\n\n---\n\n## 6. Coverage Analysis\n\n### Generate Coverage Report\n\n```bash\n# Run tests with coverage\npytest --cov=my_app --cov-report=html tests/\n\n# View coverage\nopen htmlcov/index.html  # macOS\nstart htmlcov/index.html  # Windows\n```\n\n### Coverage Configuration (.coveragerc)\n\n```ini\n[run]\nbranch = True\nsource = my_app\n\n[report]\nexclude_lines =\n    pragma: no cover\n    def __repr__\n    raise AssertionError\n    raise NotImplementedError\n    if __name__ == .__main__.:\n\n[html]\ndirectory = htmlcov\n```\n\n---\n\n## 7. Debugging with print/logging\n\n### Enable Debug Logging\n\n```python\nimport logging\nimport sys\n\n# Configure logging\nlogging.basicConfig(\n    level=logging.DEBUG,\n    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',\n    handlers=[\n        logging.StreamHandler(sys.stdout),\n        logging.FileHandler('debug.log')\n    ]\n)\n\n# Enable SDK logging\nlogging.getLogger('PowerPlatform').setLevel(logging.DEBUG)\nlogging.getLogger('azure').setLevel(logging.DEBUG)\n\n# In test\ndef test_with_logging(mock_client):\n    logger = logging.getLogger(__name__)\n    logger.debug(\"Starting test\")\n    \n    result = my_function(mock_client)\n    \n    logger.debug(f\"Result: {result}\")\n```\n\n### Pytest Capturing Output\n\n```bash\n# Show print/logging output in tests\npytest -s tests/\n\n# Capture and show on failure only\npytest --tb=short tests/\n```\n\n---\n\n## 8. Performance Testing\n\n### Measure Operation Duration\n\n```python\nimport pytest\nimport time\n\ndef test_bulk_create_performance(dataverse_client):\n    \"\"\"Test bulk create performance.\"\"\"\n    \n    payloads = [{\"name\": f\"Account {i}\"} for i in range(1000)]\n    \n    start = time.time()\n    ids = dataverse_client.create(\"account\", payloads)\n    duration = time.time() - start\n    \n    assert len(ids) == 1000\n    assert duration \u003c 10  # Should complete in under 10 seconds\n    \n    print(f\"Created 1000 records in {duration:.2f}s ({1000/duration:.0f} records/s)\")\n```\n\n### Pytest Benchmark Plugin\n\n```bash\npip install pytest-benchmark\n```\n\n```python\ndef test_query_performance(benchmark, dataverse_client):\n    \"\"\"Benchmark query performance.\"\"\"\n    \n    def get_accounts():\n        return list(dataverse_client.get(\"account\", top=100))\n    \n    result = benchmark(get_accounts)\n    assert len(result) \u003c= 100\n```\n\n---\n\n## 9. Common Testing Patterns\n\n### Testing Retry Logic\n\n```python\ndef test_retry_on_transient_error(mock_client):\n    \"\"\"Test retry on transient error.\"\"\"\n    from PowerPlatform.Dataverse.core.errors import DataverseError\n    \n    error = DataverseError(\n        message=\"Timeout\",\n        code=\"http_error\",\n        status_code=408,\n        is_transient=True\n    )\n    \n    # Fail then succeed\n    mock_client.create.side_effect = [error, [\"id-123\"]]\n    \n    from my_app import create_with_retry\n    result = create_with_retry(mock_client, \"account\", {})\n    \n    assert result == \"id-123\"\n```\n\n### Testing Filter Building\n\n```python\ndef test_filter_builder():\n    \"\"\"Test OData filter generation.\"\"\"\n    from my_app import build_account_filter\n    \n    # Test cases\n    assert build_account_filter(status=\"active\") == \"statecode eq 0\"\n    assert build_account_filter(name=\"Acme\") == \"contains(name, 'Acme')\"\n    assert build_account_filter(status=\"active\", name=\"Acme\") \\\n        == \"statecode eq 0 and contains(name, 'Acme')\"\n```\n\n### Testing Error Handling\n\n```python\ndef test_handles_missing_record(mock_client):\n    \"\"\"Test handling 404 errors.\"\"\"\n    from PowerPlatform.Dataverse.core.errors import DataverseError\n    \n    mock_client.get.side_effect = DataverseError(\n        message=\"Not found\",\n        code=\"http_error\",\n        status_code=404\n    )\n    \n    from my_app import get_account_safe\n    result = get_account_safe(mock_client, \"invalid-id\")\n    \n    assert result is None  # Returns None instead of raising\n```\n\n---\n\n## 10. Debugging Checklist\n\n| Issue | Debug Steps |\n|-------|-------------|\n| Test fails unexpectedly | Add `-s` flag to see print output |\n| Mock not called | Check method name/parameters match exactly |\n| Real API failing | Check credentials, URL, permissions |\n| Rate limiting in tests | Add delays or use smaller batches |\n| Data not found | Verify record created and not cleaned up |\n| Assertion errors | Print actual vs expected values |\n\n---\n\n## 11. See Also\n\n- [Pytest Documentation](https://docs.pytest.org/)\n- [unittest.mock Reference](https://docs.python.org/3/library/unittest.mock.html)\n- [Azure Functions Testing](https://learn.microsoft.com/en-us/azure/azure-functions/functions-reference-python#unit-testing)\n- [Dataverse SDK Examples](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/tree/main/examples)\n","description":"Based on official Azure Functions and pytest testing patterns.","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/dataverse-python-testing-debugging.instructions.md"},"manifest":{}},"content_hash":[67,116,82,169,196,79,175,147,221,166,16,213,254,165,204,61,140,32,190,54,117,198,17,132,107,73,7,220,132,216,172,2],"trust_level":"unsigned","yanked":false}