Home Assistant ResMed myAir Integration Development

Development skill for building and maintaining the Home Assistant custom component that integrates with ResMed's myAir service to pull daily CPAP data.

Overview

This skill guides development of a Home Assistant custom component following official Home Assistant developer standards, modern Python practices (3.13+), comprehensive pytest testing, and strict type safety.

Project Context

**Integration purpose:** Pull daily CPAP data from ResMed's myAir service using an undocumented API and expose it as Home Assistant sensors.

**Folder structure:**

`/custom_components/resmed_myair` — Integration code

`/tests` — pytest test suite

`/README.md` — Primary documentation

Development Guidelines

Core Principles

1. **Follow Home Assistant documentation:** All development must align with https://developers.home-assistant.io/docs/

2. **Explain as you code:** Provide clear, actionable explanations for what you're doing

3. **Incremental changes:** Focus on one conceptual change at a time, especially for public API or multi-module changes

4. **Maintain coding style:** Always preserve the project's existing code style and conventions

5. **Transparency on deviations:** When you cannot follow a guideline, explicitly state which rule is not being followed and why (e.g., missing permissions, conflicting instructions, safety policy)

Python Environment

**Python version:** 3.13+

**Home Assistant version:** Latest core version

**Virtual environment:** Use `./.venv` for all operations

**Interpreter path:** `./.venv/bin/python`

**Package installation:** You may install from `requirements-dev.txt` or `pyproject.toml` into `./.venv` without additional approval

**Avoid global installs:** Always use the repo venv unless explicitly directed otherwise

Code Quality Standards

**Type annotations:**

Add type hints to all functions and classes, including return types

Use modern Python typing features

**Documentation:**

Add descriptive docstrings to all functions and classes (PEP 257 convention)

Update existing docstrings when modifying code

Preserve all existing comments in files

**Code organization:**

Store constants in `const.py`

Use `config_flow.py` for configuration flows

Modular design with distinct files for entity types, services, and utilities

All imports at the top of files

**Tooling:**

**pre-commit hooks:** Configured in `.pre-commit-config.yaml`

**Ruff:** Code style enforcement (settings in `pyproject.toml`)

**mypy:** Static type checking (settings in `pyproject.toml`)

Local Development Workflow

**Primary tools:** `pre-commit` and `pytest` (not tox)

Run code quality checks:

```bash

pre-commit run --all-files

```

Run full test suite (default):

```bash

pytest

```

Run targeted tests (only when explicitly requested):

```bash

pytest tests/test_specific_module.py

```

**Important:** Always run pytest and pre-commit in the repository venv (`./.venv`) unless user specifies otherwise.

Error Handling & Logging

Implement robust error handling with specific exception types

**Never catch bare `Exception`** — catch specific exceptions instead

Use Home Assistant's built-in logging framework

Include debug logging for troubleshooting

**Fail-safe for missing dependencies:**

If test runs fail due to missing dev/test dependencies:

1. Attempt to install missing packages into `./.venv` if permitted, or

2. Report missing package(s) with exact `pip install` command and fail gracefully

Testing Standards

Framework and Tools

**Test framework:** pytest (not unittest)

**Home Assistant utilities:** pytest-homeassistant-custom-component

- Use `MockConfigEntry` for config entries (provided by the plugin)

- Don't create custom utilities when plugin provides them

**Mocking:** Prefer `monkeypatch` over `patch` when possible

**Shared utilities:** Use `conftest.py` for fixtures and shared test helpers

Test Organization

**One test file per integration file:** Each source file has a single corresponding test module

Add new tests to existing test modules targeting the same integration

Only create separate test modules for explicit end-to-end tests (`test_integration.py`)

Test Quality

**Type safety:** All tests must have type annotations and docstrings

**Isolation:** Use fixtures and mocks to isolate test behavior

**Parameterization:** Use `@pytest.mark.parametrize` for similar test cases

- Delete legacy placeholder tests when parameterizing

- Remove related placeholder comments

**Coverage target:** Achieve at least 80% code coverage

**Test with code changes:** Always include tests for new or changed behavior, even for non-minimal edits

Test Execution

**Default behavior:** Run full pytest suite (repository is small enough for full runs)

**Focused runs:** Only run targeted tests when user explicitly requests it

**Address warnings:** Do NOT use `--disable-warnings` — fix all warnings

Example full run:

```bash

pytest

```

Example focused run (only when requested):

```bash

pytest tests/test_sensor.py::test_specific_case

```

Git and CI/CD Workflow

Branch and PR Policy

The agent will only create branches or open pull requests when:

1. The user explicitly requests it, OR

2. The user includes the hashtag `#github-pull-request_copilot-coding-agent`

Continuous Integration

**CI/CD platform:** GitHub Actions

All code must pass CI checks before merge

CI runs pre-commit hooks and full pytest suite

Code Review Checklist

Before submitting changes:

[ ] Type annotations added to all new functions/classes

[ ] Docstrings added (PEP 257 format)

[ ] Existing comments preserved

[ ] Tests added for new/changed behavior

[ ] `pre-commit run --all-files` passes

[ ] `pytest` passes with no warnings

[ ] Coverage remains ≥80%

[ ] Changes follow Home Assistant developer docs

[ ] No bare `Exception` catches

[ ] All imports at top of file

Example: Adding a New Sensor

When adding a new sensor entity:

1. Create sensor class in `custom_components/resmed_myair/sensor.py`

2. Add type hints and docstrings

3. Define constants in `const.py`

4. Create comprehensive test module `tests/test_sensor.py`

5. Use `MockConfigEntry` from pytest-homeassistant-custom-component

6. Parameterize similar test cases

7. Run `pre-commit run --all-files`

8. Run `pytest` and verify ≥80% coverage

9. Ensure all tests pass with no warnings

Common Patterns

**Using MockConfigEntry:**

```python

from pytest_homeassistant_custom_component.common import MockConfigEntry

def test_sensor_setup(hass):

"""Test sensor platform setup."""

entry = MockConfigEntry(

domain="resmed_myair",

data={"username": "test", "password": "test"}

)

# ... rest of test

```

**Parameterized tests:**

```python

@pytest.mark.parametrize(

"input_value,expected_output",

[

(100, "100%"),

(0, "0%"),

(None, "Unknown"),

)

def test_format_percentage(input_value, expected_output):

"""Test percentage formatting with various inputs."""

assert format_percentage(input_value) == expected_output

```

Notes

This is a Home Assistant custom component for medical device data (CPAP)

The myAir API is undocumented — expect potential breaking changes

Prioritize data privacy and secure credential handling

Follow Home Assistant's entity naming and state conventions

Home Assistant ResMed myAir Integration Development

Home Assistant ResMed myAir Integration Development

Overview

Project Context

Development Guidelines

Core Principles

Python Environment

Code Quality Standards

Local Development Workflow

Error Handling & Logging

Testing Standards

Framework and Tools

Test Organization

Test Quality

Test Execution

Git and CI/CD Workflow

Branch and PR Policy

Continuous Integration

Code Review Checklist

Example: Adding a New Sensor

Common Patterns

Notes

Reviews (0)