Home Assistant Emby TDD

Overview

All code for the HA Emby integration MUST follow strict Test-Driven Development.

Write the test first. Watch it fail. Write minimal code to pass. Refactor. No exceptions.

The Iron Law

NO CODE WITHOUT A FAILING TEST FIRST

This is non-negotiable. Every function, method, class, and feature starts with a test.

Write code before test? Delete it. Start over.

No exceptions:

• Not for "simple functions"
• Not for "obvious implementations"
• Not for "just adding a property"
• Not for config flow steps
• Not for entity attributes
• Delete means delete - don't keep as "reference"

RED-GREEN-REFACTOR Cycle

RED: Write Failing Test

# tests/test_media_player.py
async def test_play_media_sends_correct_api_call(
    hass: HomeAssistant,
    mock_emby_client: MagicMock,
) -> None:
    """Test play_media calls Emby API correctly."""
    entity = create_media_player_entity(hass, mock_emby_client)

    await entity.async_play_media(
        media_type=MediaType.MOVIE,
        media_id="movie-123",
    )

    mock_emby_client.play_item.assert_called_once_with(
        item_id="movie-123",
        play_command="PlayNow",
    )

Run the test. It MUST fail. If it passes, your test is wrong.

GREEN: Write Minimal Implementation

# custom_components/embymedia/media_player.py
async def async_play_media(
    self,
    media_type: MediaType,
    media_id: str,
    enqueue: MediaPlayerEnqueue | None = None,
    announce: bool | None = None,
    **kwargs: Any,  # Required by HA interface
) -> None:
    """Play media on the Emby device."""
    await self._client.play_item(
        item_id=media_id,
        play_command="PlayNow",
    )

Run the test. It MUST pass now.

REFACTOR: Improve Without Breaking

Only refactor when tests pass. Keep them passing throughout.

Testing Patterns for HA Emby

Config Flow Tests

async def test_config_flow_user_step_success(
    hass: HomeAssistant,
    mock_emby_client: MagicMock,
) -> None:
    """Test successful user config flow."""
    result = await hass.config_entries.flow.async_init(
        DOMAIN,
        context={"source": config_entries.SOURCE_USER},
    )
    assert result["type"] is FlowResultType.FORM

    mock_emby_client.authenticate.return_value = True

    result = await hass.config_entries.flow.async_configure(
        result["flow_id"],
        user_input={
            CONF_HOST: "emby.local",
            CONF_PORT: 8096,
            CONF_API_KEY: "test-api-key",
        },
    )

    assert result["type"] is FlowResultType.CREATE_ENTRY
    assert result["title"] == "Emby Server"

Entity Tests

async def test_media_player_state_playing(
    hass: HomeAssistant,
    mock_config_entry: MockConfigEntry,
    mock_emby_client: MagicMock,
) -> None:
    """Test media player reports playing state."""
    mock_emby_client.get_playstate.return_value = PlayState(
        is_playing=True,
        is_paused=False,
    )

    mock_config_entry.add_to_hass(hass)
    await hass.config_entries.async_setup(mock_config_entry.entry_id)
    await hass.async_block_till_done()

    state = hass.states.get("media_player.emby_living_room")
    assert state.state == MediaPlayerState.PLAYING

Fixtures (conftest.py)

@pytest.fixture
def mock_emby_client() -> Generator[MagicMock, None, None]:
    """Mock the Emby API client."""
    with patch(
        "custom_components.embymedia.EmbyClient",
        autospec=True,
    ) as mock:
        client = mock.return_value
        client.authenticate.return_value = True
        client.get_server_info.return_value = ServerInfo(
            name="Test Server",
            id="server-123",
            version="4.8.0",
        )
        yield client


@pytest.fixture
def mock_config_entry() -> MockConfigEntry:
    """Create a mock config entry."""
    return MockConfigEntry(
        domain=DOMAIN,
        data={
            CONF_HOST: "emby.local",
            CONF_PORT: 8096,
            CONF_API_KEY: "test-api-key",
        },
        unique_id="server-123",
    )

Test Coverage Requirements

Minimum coverage: 100% for all new code

Every code path must be tested:

• Happy paths
• Error conditions
• Edge cases
• All config flow branches
• All entity states

Run coverage check:

pytest tests/ --cov=custom_components.embymedia --cov-report=term-missing --cov-fail-under=100

Common Rationalizations (All Wrong)

Red Flags - STOP and Start Over

If you catch yourself with ANY of these, delete your code and restart with TDD:

• Code exists without corresponding test
• Test was written after implementation
• "I'll refactor the test later"
• "The existing tests cover this"
• "This is too simple to test"
• Test passes on first run (test is wrong)

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=custom_components.embymedia --cov-report=term-missing

# Run specific test file
pytest tests/test_config_flow.py

# Run single test
pytest tests/test_media_player.py::test_play_media_sends_correct_api_call

# Stop on first failure
pytest tests/ -x

Integration with pytest-homeassistant-custom-component

Use the pytest-homeassistant-custom-component package for HA-specific fixtures:

from pytest_homeassistant_custom_component.common import (
    MockConfigEntry,
    async_fire_time_changed,
)

Key fixtures available:

• hass - Mock Home Assistant instance
• aioclient_mock - Mock aiohttp client sessions
• enable_custom_integrations - Enable custom component loading

Live Server Testing

For integration tests against a real Emby server, use environment variables.

Environment Variables

# Set in .env file (loaded by devcontainer)
EMBY_URL=https://your-emby-server.example.com
EMBY_API_KEY=your-api-key-here

Accessing Environment Variables

NEVER read .env files directly. Always use os.environ:

import os

# CORRECT
emby_url = os.environ.get("EMBY_URL")
emby_api_key = os.environ.get("EMBY_API_KEY")

# WRONG - Never do this
# from dotenv import load_dotenv
# load_dotenv()

Live Test Fixtures

import os
import pytest

@pytest.fixture
def live_emby_url() -> str | None:
    """Get live Emby URL from environment."""
    return os.environ.get("EMBY_URL")

@pytest.fixture
def live_emby_api_key() -> str | None:
    """Get live Emby API key from environment."""
    return os.environ.get("EMBY_API_KEY")

@pytest.fixture
def requires_live_server(
    live_emby_url: str | None,
    live_emby_api_key: str | None,
) -> None:
    """Skip test if live server credentials not available."""
    if not live_emby_url or not live_emby_api_key:
        pytest.skip("EMBY_URL and EMBY_API_KEY required for live tests")

Live Test Example

@pytest.mark.usefixtures("requires_live_server")
async def test_live_server_connection(
    live_emby_url: str,
    live_emby_api_key: str,
) -> None:
    """Test connection to live Emby server."""
    client = EmbyApiClient(url=live_emby_url, api_key=live_emby_api_key)
    server_info = await client.async_get_server_info()
    assert server_info.server_id is not None

Running Live Tests

# Live tests only run if environment variables are set
pytest tests/ -v

# Skip live tests explicitly
EMBY_URL= EMBY_API_KEY= pytest tests/ -v

The Bottom Line

Every line of code starts with a failing test.

No shortcuts. No exceptions. No rationalizations.

RED → GREEN → REFACTOR. Always.