alpinebits_python/tests/helpers/README.md

# Test Helpers

This directory contains helper utilities for creating test data.

## XML Builders

The `xml_builders` module provides convenient builder classes for creating reservation XML structures used in conversion service tests.

### Quick Start

```python
from tests.helpers import ReservationXMLBuilder

# Create a simple reservation
xml = (
    ReservationXMLBuilder(
        hotel_id="39054_001",
        reservation_id="12345",
        reservation_number="RES-001",
        reservation_date="2025-11-14",
    )
    .set_guest(
        guest_id="guest_001",
        first_name="John",
        last_name="Doe",
        email="john@example.com",
    )
    .add_room(
        arrival="2025-12-01",
        departure="2025-12-05",
        revenue_logis_per_day=150.0,  # Fixed revenue per night
    )
    .build_xml()
)
```

### Features

#### ReservationXMLBuilder

The main builder class for creating reservation XML structures.

**Key Features:**
- Fluent API for method chaining
- Automatic daily sales generation from arrival to departure
- Convenient revenue-per-day specification (no need to manually create each dailySale)
- Support for advertising campaign data
- Guest information with optional fields

**Example - Multi-room reservation:**

```python
xml = (
    ReservationXMLBuilder(
        hotel_id="39054_001",
        reservation_id="12345",
        reservation_number="RES-001",
        reservation_date="2025-11-14",
    )
    .set_guest(
        guest_id="guest_001",
        first_name="Jane",
        last_name="Smith",
        email="jane@example.com",
        country_code="US",
    )
    .add_room(
        arrival="2025-12-01",
        departure="2025-12-05",
        room_number="101",
        room_type="DZV",
        revenue_logis_per_day=150.0,
    )
    .add_room(
        arrival="2025-12-01",
        departure="2025-12-05",
        room_number="102",
        room_type="DZM",
        revenue_logis_per_day=200.0,
    )
    .build_xml()
)
```

#### Daily Sales Generation

The builder automatically generates `<dailySale>` entries for each day from arrival to departure (inclusive).

- **Days before departure**: Include `revenueTotal` and `revenueLogis` attributes
- **Departure day**: No revenue attributes (just the date)

**Example:**
```python
# A 3-night stay (Dec 1-4)
.add_room(
    arrival="2025-12-01",
    departure="2025-12-04",
    revenue_logis_per_day=160.0,
)
```

Generates:
```xml
<dailySales>
  <dailySale date="2025-12-01" revenueTotal="160.0" revenueLogis="160.0"/>
  <dailySale date="2025-12-02" revenueTotal="160.0" revenueLogis="160.0"/>
  <dailySale date="2025-12-03" revenueTotal="160.0" revenueLogis="160.0"/>
  <dailySale date="2025-12-04"/>  <!-- No revenue on departure day -->
</dailySales>
```

#### MultiReservationXMLBuilder

For creating XML documents with multiple reservations:

```python
from tests.helpers import ReservationXMLBuilder, MultiReservationXMLBuilder

multi_builder = MultiReservationXMLBuilder()

# Add first reservation
res1 = (
    ReservationXMLBuilder(...)
    .set_guest(...)
    .add_room(...)
)
multi_builder.add_reservation(res1)

# Add second reservation
res2 = (
    ReservationXMLBuilder(...)
    .set_guest(...)
    .add_room(...)
)
multi_builder.add_reservation(res2)

xml = multi_builder.build_xml()
```

#### RoomReservationBuilder

Low-level builder for creating individual room reservations. Usually you'll use `ReservationXMLBuilder.add_room()` instead, but this is available for advanced use cases.

```python
from tests.helpers import RoomReservationBuilder

room_builder = RoomReservationBuilder(
    arrival="2025-12-01",
    departure="2025-12-05",
    room_type="DZV",
    room_number="101",
    revenue_logis_per_day=150.0,
)

# Get the XML element (not a string)
room_elem = room_builder.build()
```

### Common Parameters

**ReservationXMLBuilder:**
- `hotel_id` - Hotel ID (required)
- `reservation_id` - Reservation ID (required)
- `reservation_number` - Reservation number (required)
- `reservation_date` - Reservation date YYYY-MM-DD (required)
- `creation_time` - Creation timestamp (optional, defaults to reservation_date + T00:00:00)
- `advertising_medium` - Advertising medium (optional)
- `advertising_partner` - Advertising partner (optional)
- `advertising_campagne` - Advertising campaign (optional)

**set_guest() parameters:**
- `guest_id` - Guest ID (required)
- `first_name` - First name (required)
- `last_name` - Last name (required)
- `email` - Email address (required)
- `language` - Language code (default: "en")
- `gender` - Gender (optional)
- `country_code` - Country code (optional)
- `country` - Country name (optional)

**add_room() parameters:**
- `arrival` - Arrival date YYYY-MM-DD (required)
- `departure` - Departure date YYYY-MM-DD (required)
- `room_type` - Room type code (default: "DZV")
- `room_number` - Room number (default: "101")
- `status` - Reservation status (default: "reserved")
- `adults` - Number of adults (default: 2)
- `children` - Number of children (default: 0)
- `infants` - Number of infants (default: 0)
- `rate_plan_code` - Rate plan code (default: "STANDARD")
- `revenue_logis_per_day` - Fixed revenue per night (optional, generates daily sales)
- `revenue_total_per_day` - Total revenue per night (optional, defaults to revenue_logis_per_day)

### See Also

- [tests/test_xml_builders.py](../test_xml_builders.py) - Unit tests demonstrating all features
- [tests/test_conversion_service.py](../test_conversion_service.py) - Integration examples (TestXMLBuilderUsage class)