canvas 0.63.0__py3-none-any.whl → 0.89.0__py3-none-any.whl

canvas_sdk/test_utils/factories/FACTORY_GUIDE.md

@@ -0,0 +1,362 @@
+# Canvas SDK Factory Guide
+
+This guide explains how to use the existing Canvas SDK test factories and how to create your own custom factories.
+
+## Available Factories
+
+The Canvas SDK provides the following built-in factories in `canvas_sdk.test_utils.factories`:
+
+### Core Entity Factories
+- **PatientFactory** - Creates test patient records
+- **StaffFactory** - Creates staff/provider records
+- **CanvasUserFactory** (UserFactory) - Creates user accounts
+- **OrganizationFactory** - Creates organization entities
+- **FacilityFactory** - Creates healthcare facilities
+- **PracticeLocationFactory** - Creates practice locations
+
+### Clinical Data Factories
+- **NoteFactory** - Creates clinical notes (automatically creates initial state)
+- **ClaimFactory** - Creates insurance claims
+- **ClaimDiagnosisCodeFactory** - Creates diagnosis codes for claims
+- **MedicationHistoryMedicationFactory** - Creates medication history records
+- **ProtocolCurrentFactory** - Creates protocol instances
+
+### Related Factories
+- **PatientAddressFactory** - Creates patient addresses
+- **StaffAddressFactory** - Creates staff addresses
+- **StaffContactPointFactory** - Creates staff contact info
+- **StaffLicenseFactory** - Creates staff licenses
+- **StaffRoleFactory** - Creates staff role assignments
+- **NoteStateChangeEventFactory** - Creates note state change events
+
+## Using Existing Factories
+
+### Basic Usage
+
+```python
+from canvas_sdk.test_utils.factories import PatientFactory, StaffFactory, NoteFactory
+
+def test_example():
+    # Create a patient with random data
+    patient = PatientFactory.create()
+
+    # Access generated fields
+    assert patient.first_name is not None
+    assert patient.last_name is not None
+    assert patient.birth_date is not None
+
+    # Patient automatically has a user account
+    assert patient.user is not None
+```
+
+### Customizing Factory Data
+
+```python
+def test_with_custom_data():
+    # Override specific fields
+    patient = PatientFactory.create(
+        first_name="John",
+        last_name="Doe",
+        birth_date=datetime.date(1980, 1, 1)
+    )
+
+    assert patient.first_name == "John"
+    assert patient.last_name == "Doe"
+```
+
+### Creating Multiple Instances
+
+```python
+def test_multiple_patients():
+    # Create 5 patients at once
+    patients = PatientFactory.create_batch(5)
+
+    assert len(patients) == 5
+    assert all(p.id is not None for p in patients)
+```
+
+### Using Factories with Related Objects
+
+```python
+def test_note_with_patient():
+    # Create a note (automatically creates patient, provider, and location)
+    note = NoteFactory.create()
+
+    assert note.patient is not None
+    assert note.provider is not None
+    assert note.location is not None
+
+    # Note automatically has initial state
+    assert note.state == NoteStates.NEW
+```
+
+### Creating Related Objects Together
+
+```python
+def test_note_for_specific_patient():
+    # Create a patient first
+    patient = PatientFactory.create(first_name="Jane")
+
+    # Create a note for that specific patient
+    note = NoteFactory.create(patient=patient)
+
+    assert note.patient.first_name == "Jane"
+```
+
+## Creating Custom Factories
+
+### Basic Custom Factory
+
+Here's how to create a custom factory for a model that doesn't have one yet:
+
+```python
+import factory
+from factory.fuzzy import FuzzyDate, FuzzyChoice
+import datetime
+
+from canvas_sdk.v1.data.appointment import Appointment as AppointmentData
+from canvas_sdk.test_utils.factories import PatientFactory, StaffFactory, PracticeLocationFactory
+
+
+class AppointmentFactory(factory.django.DjangoModelFactory):
+    """Factory for creating test Appointments."""
+
+    class Meta:
+        model = AppointmentData
+
+    # Required relationships
+    patient = factory.SubFactory(PatientFactory)
+    provider = factory.SubFactory(StaffFactory)
+    location = factory.SubFactory(PracticeLocationFactory)
+
+    # Date/time fields with reasonable defaults
+    start_time = factory.LazyFunction(
+        lambda: datetime.datetime.now() + datetime.timedelta(days=7)
+    )
+
+    # Use FuzzyChoice for fields with limited options
+    duration_minutes = FuzzyChoice([15, 30, 45, 60])
+
+    # Simple string fields
+    comment = factory.Faker("sentence")
+    description = factory.Faker("sentence")
+```
+
+### Usage of Custom Factory
+
+```python
+def test_with_custom_appointment_factory():
+    """Example test using the custom AppointmentFactory."""
+    # Basic creation
+    appointment = AppointmentFactory.create()
+
+    assert appointment.id is not None
+    assert appointment.patient is not None
+    assert appointment.provider is not None
+
+    # With custom values
+    specific_patient = PatientFactory.create(first_name="Alice")
+    appointment = AppointmentFactory.create(
+        patient=specific_patient,
+        duration_minutes=60
+    )
+
+    assert appointment.patient.first_name == "Alice"
+    assert appointment.duration_minutes == 60
+```
+
+### Advanced Factory Features
+
+#### 1. Post-Generation Hooks
+
+Use `@factory.post_generation` to perform actions after object creation:
+
+```python
+class TaskFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Task
+
+    title = factory.Faker("sentence")
+    patient = factory.SubFactory(PatientFactory)
+
+    @factory.post_generation
+    def add_labels(self, create, extracted, **kwargs):
+        """Add labels to the task after creation."""
+        if not create:
+            return
+
+        if extracted:
+            # Use provided labels
+            for label in extracted:
+                self.labels.add(label)
+        else:
+            # Add default labels
+            self.labels.add("test-label")
+
+# Usage:
+task = TaskFactory.create(add_labels=["urgent", "review"])
+```
+
+#### 2. Lazy Attributes
+
+Use `factory.LazyAttribute` for fields that depend on other fields:
+
+```python
+class StaffFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Staff
+
+    first_name = factory.Faker("first_name")
+    last_name = factory.Faker("last_name")
+
+    # Email based on name
+    email = factory.LazyAttribute(
+        lambda obj: f"{obj.first_name.lower()}.{obj.last_name.lower()}@example.com"
+    )
+```
+
+#### 3. Sequences
+
+Use `factory.Sequence` for unique values:
+
+```python
+class PatientFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Patient
+
+    # Creates patient-1@example.com, patient-2@example.com, etc.
+    email = factory.Sequence(lambda n: f"patient-{n}@example.com")
+```
+
+#### 4. Conditional SubFactories
+
+Use `factory.Maybe` for conditional relationships:
+
+```python
+class NoteFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Note
+
+    is_signed = factory.Faker("boolean")
+
+    # Only create signing provider if note is signed
+    signing_provider = factory.Maybe(
+        "is_signed",
+        yes_declaration=factory.SubFactory(StaffFactory),
+        no_declaration=None
+    )
+```
+
+## Factory Best Practices
+
+### 1. Use Factories for All Test Data
+
+```python
+# Good: Using factories
+def test_patient_lookup():
+    patient = PatientFactory.create(first_name="John")
+    result = lookup_patient(patient.id)
+    assert result.first_name == "John"
+
+# Avoid: Manual object creation
+def test_patient_lookup_manual():
+    patient = Patient.objects.create(
+        first_name="John",
+        last_name="Doe",
+        birth_date=datetime.date(1980, 1, 1),
+        # ... many more required fields
+    )
+```
+
+### 2. Create Factories in a Shared Location
+
+Place custom factories in a dedicated file:
+
+```
+tests/
+  ├── __init__.py
+  ├── factories.py          # Your custom factories
+  └── test_my_plugin.py     # Your tests
+```
+
+### 3. Override Only What You Need
+
+```python
+# Good: Only override relevant fields
+patient = PatientFactory.create(first_name="Alice")
+
+# Avoid: Overriding everything
+patient = PatientFactory.create(
+    first_name="Alice",
+    last_name="Smith",  # Could use default
+    birth_date=datetime.date(1990, 1, 1),  # Could use default
+)
+```
+
+### 4. Use build() Instead of create() When Database Isn't Needed
+
+```python
+# Creates object in database
+patient = PatientFactory.create()
+
+# Creates object in memory only (faster for unit tests)
+patient = PatientFactory.build()
+```
+
+## Common Patterns
+
+### Testing Protocols with Factories
+
+```python
+from canvas_sdk.test_utils.factories import PatientFactory, NoteFactory
+
+def test_my_protocol():
+    # Create test data
+    patient = PatientFactory.create(
+        first_name="Test",
+        birth_date=datetime.date(1980, 1, 1)
+    )
+
+    note = NoteFactory.create(patient=patient)
+
+    # Create a mock event
+    mock_event = Mock()
+    mock_event.context = {"patient": {"id": patient.id}}
+
+    # Test your protocol
+    protocol = MyProtocol(event=mock_event)
+    effects = protocol.compute()
+
+    assert len(effects) > 0
+```
+
+### Testing API Handlers with Factories
+
+```python
+from canvas_sdk.test_utils.factories import PatientFactory, StaffFactory
+
+def test_appointment_api():
+    # Create test data
+    patient = PatientFactory.create()
+    provider = StaffFactory.create()
+
+    # Create API request
+    api = AppointmentAPI(event=mock_event)
+    api.request = DummyRequest(
+        json_body={
+            "patient_id": str(patient.id),
+            "provider_id": str(provider.id),
+            "start_time": "2024-01-01T10:00:00"
+        }
+    )
+
+    # Test the API
+    result = api.post()
+    assert result[0].status_code == HTTPStatus.CREATED
+```
+
+## References
+
+- [Factory Boy Documentation](https://factoryboy.readthedocs.io/)
+- [Canvas SDK Testing Utils](https://docs.canvasmedical.com/sdk/testing-utils/)
+- [Canvas SDK Factory Source](https://github.com/canvas-medical/canvas-plugins/tree/main/canvas_sdk/test_utils/factories)

canvas_sdk/test_utils/factories/__init__.py

@@ -1,13 +1,128 @@
+from .calendar import CalendarFactory, EventFactory
+from .claim import (
+    ClaimCommentFactory,
+    ClaimCoverageFactory,
+    ClaimFactory,
+    ClaimLabelFactory,
+    ClaimProviderFactory,
+    ClaimQueueFactory,
+    ClaimSubmissionFactory,
+)
+from .claim_diagnosis_code import ClaimDiagnosisCodeFactory
+from .coverage import CoverageFactory
 from .facility import FacilityFactory
+from .imaging import ImagingOrderFactory, ImagingReportFactory, ImagingReviewFactory
+from .lab import (
+    LabOrderFactory,
+    LabOrderReasonConditionFactory,
+    LabOrderReasonFactory,
+    LabPartnerFactory,
+    LabPartnerTestFactory,
+    LabReportFactory,
+    LabReviewFactory,
+    LabTestFactory,
+    LabValueCodingFactory,
+    LabValueFactory,
+)
+from .medication_history import (
+    MedicationHistoryMedicationCodingFactory,
+    MedicationHistoryMedicationFactory,
+    MedicationHistoryResponseFactory,
+)
+from .note import NoteFactory, NoteStateChangeEventFactory, NoteTypeFactory
+from .organization import (
+    OrganizationAddressFactory,
+    OrganizationContactPointFactory,
+    OrganizationFactory,
+)
 from .patient import PatientAddressFactory, PatientFacilityAddressFactory, PatientFactory
+from .practicelocation import (
+    PracticeLocationAddressFactory,
+    PracticeLocationContactPointFactory,
+    PracticeLocationFactory,
+    PracticeLocationSettingFactory,
+)
 from .protocol_current import ProtocolCurrentFactory
+from .referral import ReferralFactory, ReferralReportFactory, ReferralReviewFactory
+from .staff import (
+    StaffAddressFactory,
+    StaffContactPointFactory,
+    StaffFactory,
+    StaffLicenseFactory,
+    StaffPhotoFactory,
+    StaffRoleFactory,
+)
+from .task import (
+    TaskCommentFactory,
+    TaskFactory,
+    TaskLabelFactory,
+    TaskMetadataFactory,
+    TaskTaskLabelFactory,
+)
+from .uncategorized_clinical_document import (
+    UncategorizedClinicalDocumentFactory,
+    UncategorizedClinicalDocumentReviewFactory,
+)
 from .user import CanvasUserFactory
 
 __all__ = (
+    "CalendarFactory",
     "CanvasUserFactory",
+    "ClaimFactory",
+    "ClaimCommentFactory",
+    "ClaimCoverageFactory",
+    "ClaimDiagnosisCodeFactory",
+    "ClaimLabelFactory",
+    "ClaimProviderFactory",
+    "ClaimQueueFactory",
+    "ClaimSubmissionFactory",
+    "CoverageFactory",
+    "EventFactory",
     "FacilityFactory",
+    "ImagingOrderFactory",
+    "ImagingReportFactory",
+    "ImagingReviewFactory",
+    "LabOrderFactory",
+    "LabOrderReasonConditionFactory",
+    "LabOrderReasonFactory",
+    "LabPartnerFactory",
+    "LabPartnerTestFactory",
+    "LabReportFactory",
+    "LabReviewFactory",
+    "LabTestFactory",
+    "LabValueCodingFactory",
+    "LabValueFactory",
+    "MedicationHistoryMedicationFactory",
+    "MedicationHistoryMedicationCodingFactory",
+    "MedicationHistoryResponseFactory",
+    "NoteFactory",
+    "NoteStateChangeEventFactory",
+    "NoteTypeFactory",
+    "OrganizationAddressFactory",
+    "OrganizationContactPointFactory",
+    "OrganizationFactory",
     "PatientAddressFactory",
     "PatientFacilityAddressFactory",
     "PatientFactory",
+    "PracticeLocationFactory",
+    "PracticeLocationAddressFactory",
+    "PracticeLocationContactPointFactory",
+    "PracticeLocationSettingFactory",
     "ProtocolCurrentFactory",
+    "ReferralFactory",
+    "ReferralReportFactory",
+    "ReferralReviewFactory",
+    "StaffFactory",
+    "StaffPhotoFactory",
+    "StaffRoleFactory",
+    "StaffLicenseFactory",
+    "StaffContactPointFactory",
+    "StaffAddressFactory",
+    "TaskCommentFactory",
+    "TaskFactory",
+    "TaskLabelFactory",
+    "TaskMetadataFactory",
+    "TaskTaskLabelFactory",
+    "UncategorizedClinicalDocumentFactory",
+    "UncategorizedClinicalDocumentReviewFactory",
 )

canvas_sdk/test_utils/factories/calendar.py

@@ -0,0 +1,24 @@
+import factory
+
+from canvas_sdk.v1.data import Calendar, Event
+
+
+class EventFactory(factory.django.DjangoModelFactory[Event]):
+    """Factory for creating an Event."""
+
+    class Meta:
+        model = Event
+
+    title = "Calendar Event"
+    calendar = factory.SubFactory("canvas_sdk.test_utils.factories.CalendarFactory")
+    starts_at = factory.Faker("date_time")
+    ends_at = factory.Faker("date_time")
+
+
+class CalendarFactory(factory.django.DjangoModelFactory[Calendar]):
+    """Factory for creating Calendar."""
+
+    class Meta:
+        model = Calendar
+
+    title = "Calendar"

canvas_sdk/test_utils/factories/claim.py

@@ -0,0 +1,81 @@
+import factory
+
+from canvas_sdk.v1.data import (
+    Claim,
+    ClaimComment,
+    ClaimCoverage,
+    ClaimLabel,
+    ClaimProvider,
+    ClaimQueue,
+    ClaimSubmission,
+)
+
+
+class ClaimCoverageFactory(factory.django.DjangoModelFactory[ClaimCoverage]):
+    """Factory for creating ClaimCoverage."""
+
+    class Meta:
+        model = ClaimCoverage
+
+    claim = factory.SubFactory("canvas_sdk.test_utils.factories.claim.ClaimFactory")
+    coverage = factory.SubFactory("canvas_sdk.test_utils.factories.CoverageFactory")
+
+
+class ClaimQueueFactory(factory.django.DjangoModelFactory[ClaimQueue]):
+    """Factory for creating ClaimQueue."""
+
+    class Meta:
+        model = ClaimQueue
+        django_get_or_create = ("queue_sort_ordering",)
+
+    queue_sort_ordering = 5
+    name = "Claim: Filed"
+
+
+class ClaimFactory(factory.django.DjangoModelFactory[Claim]):
+    """Factory for creating Claim."""
+
+    class Meta:
+        model = Claim
+
+    note = factory.SubFactory("canvas_sdk.test_utils.factories.NoteFactory")
+    current_queue = factory.SubFactory(ClaimQueueFactory)
+
+
+class ClaimCommentFactory(factory.django.DjangoModelFactory[ClaimComment]):
+    """Factory for creating ClaimComment."""
+
+    class Meta:
+        model = ClaimComment
+
+    claim = factory.SubFactory(ClaimFactory)
+    comment = "Need to message Dr. House"
+
+
+class ClaimProviderFactory(factory.django.DjangoModelFactory[ClaimProvider]):
+    """Factory for creating ClaimProvider."""
+
+    class Meta:
+        model = ClaimProvider
+
+    claim = factory.SubFactory(ClaimFactory)
+
+
+class ClaimLabelFactory(factory.django.DjangoModelFactory[ClaimLabel]):
+    """Factory for creating ClaimLabel."""
+
+    class Meta:
+        model = ClaimLabel
+
+    claim = factory.SubFactory(ClaimFactory)
+    label = factory.SubFactory("canvas_sdk.test_utils.factories.TaskLabelFactory")
+
+
+class ClaimSubmissionFactory(factory.django.DjangoModelFactory[ClaimSubmission]):
+    """Factory for creating ClaimSubmission."""
+
+    class Meta:
+        model = ClaimSubmission
+
+    claim = factory.SubFactory(ClaimFactory)
+    clearinghouse_claim_id = "123456"

canvas_sdk/test_utils/factories/claim_diagnosis_code.py

@@ -0,0 +1,16 @@
+import factory
+from factory.fuzzy import FuzzyInteger
+
+from canvas_sdk.v1.data import ClaimDiagnosisCode
+
+
+class ClaimDiagnosisCodeFactory(factory.django.DjangoModelFactory[ClaimDiagnosisCode]):
+    """Factory for creating a ClaimDiagnosisCode."""
+
+    class Meta:
+        model = ClaimDiagnosisCode
+
+    rank = FuzzyInteger(1, 12)  # ICD-10 allows up to 12 diagnosis codes on a claim
+    code = factory.Faker("bothify", text="?##.##")  # ICD-10 format like A01.23
+    display = factory.Faker("sentence", nb_words=4)  # Human readable diagnosis description
+    claim = factory.SubFactory("canvas_sdk.test_utils.factories.ClaimFactory")

canvas_sdk/test_utils/factories/coverage.py

@@ -0,0 +1,17 @@
+import factory
+
+from canvas_sdk.v1.data import Coverage
+
+
+class CoverageFactory(factory.django.DjangoModelFactory[Coverage]):
+    """Factory for creating a Coverage."""
+
+    class Meta:
+        model = Coverage
+
+    patient = factory.SubFactory("canvas_sdk.test_utils.factories.PatientFactory")
+    plan = "Healthy Families of California"
+    group = "San Francisco Mail Carriers"
+    coverage_rank = 1
+    id_number = "1098659867"
+    coverage_start_date = factory.Faker("date")

canvas_sdk/test_utils/factories/imaging.py

@@ -0,0 +1,74 @@
+import datetime
+import json
+
+import factory
+from django.utils import timezone
+from factory.fuzzy import FuzzyDate
+
+from canvas_sdk.v1.data import ImagingOrder, ImagingReport, ImagingReview
+from canvas_sdk.v1.data.common import (
+    DocumentReviewMode,
+    OrderStatus,
+    ReviewPatientCommunicationMethod,
+    ReviewStatus,
+)
+from canvas_sdk.v1.data.imaging import ImagingReport as ImagingReportModel
+
+
+class ImagingOrderFactory(factory.django.DjangoModelFactory[ImagingOrder]):
+    """Factory for creating an ImagingOrder."""
+
+    class Meta:
+        model = ImagingOrder
+
+    patient = factory.SubFactory("canvas_sdk.test_utils.factories.PatientFactory")
+    note = factory.SubFactory("canvas_sdk.test_utils.factories.NoteFactory")
+    imaging = factory.Faker("text", max_nb_chars=1024)
+    imaging_center = None  # Optional field
+    note_to_radiologist = factory.Faker("text", max_nb_chars=1024)
+    internal_comment = factory.Faker("text", max_nb_chars=1024)
+    status = OrderStatus.REQUESTED
+    date_time_ordered = factory.LazyFunction(lambda: timezone.now())
+    priority = factory.Faker("random_element", elements=["routine", "urgent", "stat"])
+    ordering_provider = factory.SubFactory("canvas_sdk.test_utils.factories.StaffFactory")
+    delegated = False
+    task_ids = factory.LazyFunction(lambda: json.dumps([]))
+
+
+class ImagingReviewFactory(factory.django.DjangoModelFactory[ImagingReview]):
+    """Factory for creating an ImagingReview."""
+
+    class Meta:
+        model = ImagingReview
+
+    patient_communication_method = ReviewPatientCommunicationMethod.DELEGATED_CALL_CAN_LEAVE_MESSAGE
+    internal_comment = factory.Faker("text", max_nb_chars=2048)
+    message_to_patient = factory.Faker("text", max_nb_chars=2048)
+    is_released_to_patient = False
+    status = ReviewStatus.STATUS_REVIEWING
+    patient = factory.SubFactory("canvas_sdk.test_utils.factories.PatientFactory")
+
+
+class ImagingReportFactory(factory.django.DjangoModelFactory[ImagingReport]):
+    """Factory for creating an ImagingReport."""
+
+    class Meta:
+        model = ImagingReport
+
+    review_mode = DocumentReviewMode.REVIEW_REQUIRED
+    junked = False
+    requires_signature = False
+    assigned_date = factory.LazyFunction(lambda: timezone.now())
+    patient = factory.SubFactory("canvas_sdk.test_utils.factories.PatientFactory")
+    order = None  # Optional field
+    source = ImagingReportModel.ImagingReportSource.DIRECTLY_REPORT
+    name = factory.Faker("text", max_nb_chars=255)
+    result_date = FuzzyDate(
+        start_date=datetime.date.today() - datetime.timedelta(days=365),
+        end_date=datetime.date.today(),
+    )
+    original_date = FuzzyDate(
+        start_date=datetime.date.today() - datetime.timedelta(days=365),
+        end_date=datetime.date.today(),
+    )
+    review = None  # Optional field