Add property-based tests for label normalisation idempotency

[coderabbitai]

Background

PR #6 (#6) introduced create_labels/sync.py, which normalises remote GitHub label fields (colour uppercasing, description trimming) before comparing them with the desired LabelSpec. Normalisation invariants are enforced in LabelSpec.__post_init__ but no property-based tests verify that sync_labels returns "unchanged" for the full space of denormalised GitHub responses that are semantically equivalent after normalisation.

Required work

• Add hypothesis to the [dependency-groups].dev section of pyproject.toml.
• Add property tests in tests/test_sync.py (or a new tests/test_sync_properties.py) that use @given strategies to generate:
  • arbitrary lowercase/mixed-case six-character hex colour strings (with and without a leading #);
  • arbitrary description strings with leading/trailing whitespace.
• Assert that sync_labels returns LabelSyncResult(name, "unchanged") and makes no update calls whenever the normalised remote values match the configured LabelSpec.

Acceptance criteria

• hypothesis is declared as a dev dependency.
• At least one @given-decorated test verifies colour-case idempotency.
• At least one @given-decorated test verifies description-whitespace idempotency.
• make test passes with the new property tests included.

Raised by @leynos following review of PR #6.

[coderabbitai]

🔗 Related PRs

leynos/repovec-appliance#23 - Add proptest property tests for Qdrant Quadlet parser and validator (#17) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Add hypothesis to [dependency-groups].dev in pyproject.toml.
• Create tests/test_sync_properties.py with @given-decorated tests using custom strategies for denormalised colour and description values.
• Reuse existing FakeLabel and FakeRepository test doubles to simulate GitHub API responses.
• Assert idempotency by confirming sync_labels returns "unchanged" and triggers no update calls for all generated inputs.

Design Choices

Design Choice 1: Test file location

Options Considered:

1. Add @given-decorated tests to the existing tests/test_sync.py alongside unit tests.
2. Create a new tests/test_sync_properties.py dedicated to property-based tests.

Chosen Option: 2

Rationale: A separate file provides clearer separation between deterministic unit tests and generative property tests, making maintenance and test identification simpler.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Introduce Hypothesis and Property-Based Tests

Add the Hypothesis library as a dev dependency and create property-based tests verifying that label normalisation is idempotent—ensuring sync_labels reports "unchanged" regardless of how GitHub formats semantically equivalent colour and description values.

Task 1: Add Hypothesis Dev Dependency

Add hypothesis to the project's dev dependencies so property-based test strategies are available.

• Insert "hypothesis" into the [dependency-groups] dev list in pyproject.toml, alongside existing test libraries.

Task 2: Create Property Test Module

Establish a new test module for property-based tests covering sync_labels normalisation invariants.

• Create tests/test_sync_properties.py.
• Import hypothesis.given and hypothesis.strategies for test decoration and value generation.
• Import LabelSpec, sync_labels, LabelSyncResult from production code.
• Import make_fake_label, make_fake_repository from tests/test_helpers.py to follow established test double patterns.

Task 3: Implement Colour-Case Idempotency Test

Add a @given-decorated test proving that any valid six-character hex colour string, regardless of case or leading #, normalises to match the LabelSpec and produces "unchanged".

• Define a Hypothesis strategy generating six-character strings from 0-9A-Fa-f, then randomly prepend # or not, and randomly transform case (lower, upper, mixed).
• Construct a LabelSpec with the canonical (uppercased, no prefix) colour.
• Construct a FakeLabel with the generated denormalised colour.
• Call sync_labels and assert the result is LabelSyncResult(name, "unchanged").
• Assert the FakeLabel.updates list remains empty, confirming no update API call occurred.

Task 4: Implement Description-Whitespace Idempotency Test

Add a @given-decorated test proving that descriptions with arbitrary leading/trailing whitespace normalise correctly and produce "unchanged".

• Define a Hypothesis strategy generating a non-empty base description string, then wrapping it with random amounts of leading/trailing whitespace (spaces, tabs, newlines).
• Construct a LabelSpec with the stripped description.
• Construct a FakeLabel with the whitespace-padded description.
• Call sync_labels and assert the result is LabelSyncResult(name, "unchanged").
• Assert the FakeLabel.updates list remains empty.

Task 5: Verify Test Execution

Confirm the new property tests integrate correctly with the existing test suite.

• Run make test (or equivalent pytest invocation) to ensure all tests pass, including the new property-based tests.
• Verify Hypothesis generates sufficient examples without timeouts (the project enforces a 30-second per-test limit).

🤖 Prompt for AI agents

Implement the Hypothesis dev dependency and the full
`tests/test_sync_properties.py` property-based test module in one phase. The
goal is to verify that `sync_labels` returns `"unchanged"` for any semantically
equivalent but denormalised GitHub label responses.

**1. Update `pyproject.toml`**
- Insert `"hypothesis"` into the `[dependency-groups]` `dev` list, alongside
existing test libraries.

**2. Create `tests/test_sync_properties.py`**
- Import `hypothesis.given` and `hypothesis.strategies`.
- Import `LabelSpec`, `sync_labels`, and `LabelSyncResult` from production code.
- Import `make_fake_label` and `make_fake_repository` from
`tests/test_helpers.py`.

**3. Implement colour-case idempotency test**
- Define a Hypothesis strategy that generates six-character strings from
`0-9A-Fa-f`, then randomly prepends `#` or not, and randomly transforms case
(lower, upper, mixed).
- Construct a `LabelSpec` with the canonical (uppercased, no prefix) colour.
- Construct a `FakeLabel` with the generated denormalised colour.
- Call `sync_labels` and assert the result is `LabelSyncResult(name,
"unchanged")`.
- Assert `FakeLabel.updates` remains empty, confirming no update API call
occurred.

**4. Implement description-whitespace idempotency test**
- Define a Hypothesis strategy that generates a non-empty base description
string, then wraps it with random amounts of leading/trailing whitespace
(spaces, tabs, newlines).
- Construct a `LabelSpec` with the stripped description.
- Construct a `FakeLabel` with the whitespace-padded description.
- Call `sync_labels` and assert the result is `LabelSyncResult(name,
"unchanged")`.
- Assert `FakeLabel.updates` remains empty.

**5. Verify execution**
- Run `make test` (or equivalent pytest invocation) to confirm all tests pass,
including the new property-based tests.
- Ensure Hypothesis generates sufficient examples without exceeding the
project's 30-second per-test timeout limit.

Research

The codebase is a GitHub label synchronisation tool. create_labels/sync.py contains sync_labels, which normalises remote label fields (uppercasing colours, stripping description whitespace) before comparing with LabelSpec objects. Tests reside in tests/ and use hand-rolled test doubles (FakeLabel, FakeRepository) from tests/test_helpers.py. The unittest.mock module is banned; hypothesis is not currently installed.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Implement the Hypothesis dev dependency and the full
`tests/test_sync_properties.py` property-based test module in one phase. The
goal is to verify that `sync_labels` returns `"unchanged"` for any semantically
equivalent but denormalised GitHub label responses.

**1. Update `pyproject.toml`**
- Insert `"hypothesis"` into the `[dependency-groups]` `dev` list, alongside
existing test libraries.

**2. Create `tests/test_sync_properties.py`**
- Import `hypothesis.given` and `hypothesis.strategies`.
- Import `LabelSpec`, `sync_labels`, and `LabelSyncResult` from production code.
- Import `make_fake_label` and `make_fake_repository` from
`tests/test_helpers.py`.

**3. Implement colour-case idempotency test**
- Define a Hypothesis strategy that generates six-character strings from
`0-9A-Fa-f`, then randomly prepends `#` or not, and randomly transforms case
(lower, upper, mixed).
- Construct a `LabelSpec` with the canonical (uppercased, no prefix) colour.
- Construct a `FakeLabel` with the generated denormalised colour.
- Call `sync_labels` and assert the result is `LabelSyncResult(name,
"unchanged")`.
- Assert `FakeLabel.updates` remains empty, confirming no update API call
occurred.

**4. Implement description-whitespace idempotency test**
- Define a Hypothesis strategy that generates a non-empty base description
string, then wraps it with random amounts of leading/trailing whitespace
(spaces, tabs, newlines).
- Construct a `LabelSpec` with the stripped description.
- Construct a `FakeLabel` with the whitespace-padded description.
- Call `sync_labels` and assert the result is `LabelSyncResult(name,
"unchanged")`.
- Assert `FakeLabel.updates` remains empty.

**5. Verify execution**
- Run `make test` (or equivalent pytest invocation) to confirm all tests pass,
including the new property-based tests.
- Ensure Hypothesis generates sufficient examples without exceeding the
project's 30-second per-test timeout limit.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!