# CheckboxGroupElement

> Full API (methods, signatures, descriptions): see [api-reference.md](../../skills/vaadin-playwright-test/api-reference.md). This note covers only behaviour that isn't obvious from the signatures.

## Items are addressed by label, not by value

`CheckboxGroup`'s client-side `value` is an array of server-generated item
keys (`"1"`, `"2"`, …), not of the item strings a test knows about. Every
selection method therefore takes the checkbox's **visible label**, and
`getSelectedValues()` returns labels as well.

```java
CheckboxGroupElement group = CheckboxGroupElement.getByLabel(page, "Toppings");

group.selectByLabel("Cheese", "Ham");
group.assertSelected("Cheese", "Ham");

group.deselectByLabel("Ham");
assertEquals(List.of("Cheese"), group.getSelectedValues());

group.deselectAll();
group.assertSelected(); // no argument asserts an empty selection
```

Labels are matched by accessible name (ARIA role `checkbox`), the same way
`CheckboxElement.getByLabel(Locator, String)` matches within a scope: the whole
label, case-sensitively. `selectByLabel("Option 1")` therefore leaves an
`Option 10` checkbox alone, and a partial label reaches nothing. Two checkboxes
carrying the same label make the lookup fail with a Playwright strict-mode
error; reach those through `getCheckboxes()` instead.

## assertSelected is exhaustive

`assertSelected(String...)` asserts the *complete* selection: the number of
checked checkboxes must equal the number of labels passed, and each label must
be checked. Calling it with no argument (or `null`) asserts that nothing is
selected.

## Individual checkboxes

Items are exposed as regular `CheckboxElement` instances, so the whole checkbox
API — including per-item enablement from `setItemEnabledProvider` — is
available:

```java
group.getCheckbox("Ham").assertDisabled();
group.getCheckboxes().forEach(CheckboxElement::assertNotChecked);
```