# SemanticScreen

Source: /tuil/docs/reference/packages/testing/api/semantic-screen
Locale: en

class exported by @mwillbanks/tuil-testing.



{/* Generated by tooling/docs/generate-reference.ts. */}

## class [#class]

Public class exported by `@mwillbanks/tuil-testing`.

```ts
export class SemanticScreen {
  constructor(readonly snapshot: () => SemanticSnapshot) {}

  frame(): string {
    return this.snapshot().frame;
  }

  getByRole(
    role: SemanticRole,
    query: SemanticQuery = {},
  ): QueryableSemanticNode {
    return this.#one(
      this.snapshot().nodes.filter(
        (node) =>
          node.role === role &&
          matchesText(node.label, query.name) &&
          (query.selected === undefined || node.selected === query.selected) &&
          (query.checked === undefined || node.checked === query.checked) &&
          (query.disabled === undefined || node.disabled === query.disabled),
      ),
      describe("role", { role, ...query }),
    );
  }

  getAllByRole(
    role: SemanticRole,
    query: SemanticQuery = {},
  ): readonly QueryableSemanticNode[] {
    const matches = this.snapshot().nodes.filter(
      (node) =>
        node.role === role &&
        matchesText(node.label, query.name) &&
        (query.selected === undefined || node.selected === query.selected) &&
        (query.checked === undefined || node.checked === query.checked) &&
        (query.disabled === undefined || node.disabled === query.disabled),
    );
    if (matches.length === 0) {
      throw new Error(
        `Unable to find any semantic nodes by ${describe("role", role)}`,
      );
    }
    return matches;
  }

  getByLabelText(label: string | RegExp): QueryableSemanticNode {
    return this.#one(
      this.snapshot().nodes.filter((node) => matchesText(node.label, label)),
      describe("label", label),
    );
  }

  getByText(text: string | RegExp): QueryableSemanticNode {
    return this.#one(
      this.snapshot().nodes.filter(
        (node) => matchesText(node.text, text) || matchesText(node.label, text),
      ),
      describe("text", text),
    );
  }

  getByTestId(testId: string): QueryableSemanticNode {
    return this.#one(
      this.snapshot().nodes.filter((node) => node.testId === testId),
      describe("test id", testId),
    );
  }

  #one(
    matches: readonly QueryableSemanticNode[],
    description: string,
  ): QueryableSemanticNode {
    if (matches.length === 0) {
      throw new Error(`Unable to find a semantic node by ${description}`);
    }
    if (matches.length > 1) {
      throw new Error(`Found multiple semantic nodes by ${description}`);
    }
    return matches[0] as QueryableSemanticNode;
  }
}
```

## Members [#members]

| Member           | Type                                                                                        | Required | Description                                                                                                                      | Related types                                                                                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__constructor`  | `any`                                                                                       | Yes      | The `__constructor` member uses the `any` contract.                                                                              | —                                                                                                                                                                                                                                  |
| `frame`          | `() => string`                                                                              | Yes      | The `frame` member uses the `() => string` contract.                                                                             | —                                                                                                                                                                                                                                  |
| `getByRole`      | `(role: SemanticRole, query?: SemanticQuery) => QueryableSemanticNode`                      | Yes      | The `getByRole` member uses the `(role: SemanticRole, query?: SemanticQuery) => QueryableSemanticNode` contract.                 | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node), [`SemanticQuery`](/tuil/docs/reference/packages/testing/api/semantic-query), [`SemanticRole`](/tuil/docs/reference/packages/core/api/semantic-role) |
| `getAllByRole`   | `(role: SemanticRole, query?: SemanticQuery) => readonly QueryableSemanticNode[]`           | Yes      | The `getAllByRole` member uses the `(role: SemanticRole, query?: SemanticQuery) => readonly QueryableSemanticNode[]` contract.   | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node), [`SemanticQuery`](/tuil/docs/reference/packages/testing/api/semantic-query), [`SemanticRole`](/tuil/docs/reference/packages/core/api/semantic-role) |
| `getByLabelText` | `(label: string \| RegExp) => QueryableSemanticNode`                                        | Yes      | The `getByLabelText` member uses the `(label: string \| RegExp) => QueryableSemanticNode` contract.                              | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)                                                                                                                                            |
| `getByText`      | `(text: string \| RegExp) => QueryableSemanticNode`                                         | Yes      | The `getByText` member uses the `(text: string \| RegExp) => QueryableSemanticNode` contract.                                    | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)                                                                                                                                            |
| `getByTestId`    | `(testId: string) => QueryableSemanticNode`                                                 | Yes      | The `getByTestId` member uses the `(testId: string) => QueryableSemanticNode` contract.                                          | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)                                                                                                                                            |
| `#one`           | `(matches: readonly QueryableSemanticNode[], description: string) => QueryableSemanticNode` | Yes      | The `#one` member uses the `(matches: readonly QueryableSemanticNode[], description: string) => QueryableSemanticNode` contract. | [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)                                                                                                                                            |

## Parameters [#parameters]

This declaration has no public members.

## Returns [#returns]

This declaration does not return a value.

## Throws [#throws]

No thrown errors are documented for this declaration.

## Related types [#related-types]

* [`QueryableSemanticNode`](/tuil/docs/reference/packages/testing/api/queryable-semantic-node)
* [`SemanticQuery`](/tuil/docs/reference/packages/testing/api/semantic-query)
* [`SemanticSnapshot`](/tuil/docs/reference/packages/testing/api/semantic-snapshot)

## Source [#source]

[View the secondary source reference](https://github.com/mwillbanks/tuil/blob/main/packages/testing/src/index.ts)

## Package [#package]

[@mwillbanks/tuil-testing](/tuil/docs/reference/packages/testing)