API proposal for Jest matchers migration

This issue describes the desired API regarding Jest matchers to be included in RNTL package, and that should replace the Jest Native package matchers.

Problems with the current Jest Native matchers:

• lack of maintainers
• inconsistent RN env simulation vs RNTL
• potential version mismatch between JN and RNTL packages
• matchers frequently relying on RN implementation details prone to break in case of RN change

The goals of this initiative are as follows:

• Bring non-maintained Jest Native matchers into well-maintained RNTL project
• Tie matchers to RNTL release hence preventing matcher incompatibility, full test coverage
• Review and improve internal matcher implementation, align behaviour with RNTL
• Add missing matchers, based primarily on Jest DOM matchers
• Provide gradual migration path for existing users of @testing-library/jest-native

Matchers to keep

• toBeOnTheScreen - feature: Jest matchers core #1454
• toBeVisible - feat: toBeVisible matcher #1465
• toBeEmptyElement - feat: toBeEmptyElement matcher #1462
• toBeDisabled + * toBeEnabled - feat: toBeDisabled matcher #1469
• toContainElement feat: toContainElement matcher #1495
• toHaveProp feat: toHaveProp matcher #1477
• toHaveStyle feat: toHaveStyle matcher #1487
• toHaveAccessibleValue Implement toHaveAccessibilityValue matcher #1496 (renamed from toHaveAccessibilityValue to match Jest DOM convention)

Matchers to change signature

• toHaveTextContent - feat: toHaveTextContent() matcher #1461
  1. exact match by default
  2. accept TextMatcherOptions as options (in line with most queries),

Matchers to add

• toHaveDisplayValue - feat: toHaveDisplayValue matcher #1463, based on Jest DOM matcher
• toBeChecked/toBePartiallyChecked based on Jest DOM matcher feat: toBeChecked & toBePartiallyChecked matcher #1479
• toBeSelected feat: implement toBeSelected matcher #1488 - replacing toHaveAccessibilityState, elements with acccessibiltyState: { selected }
• toBeBusy feat: toBeBusy() matcher #1493 - replacing toHaveAccessibilityState, elements with acccessibiltyState: { busy }
• toBeExpanded feat: toBeExpanded matcher #1497 - replacing toHaveAccessibilityState, elements with acccessibiltyState: { expanded }
• toHaveAccessibleName based on Jest DOM matcher, elements with text content or accessibilityLabel prop

Matchers to remove

• toHaveAccessibilityState - to be replaced by toBeDisabled, toBe(Partially)Checked, etc

Migration path

• Create RNTL documentation for matchers
• Create migration guide
• Expose legacy export in Jest Native package
• Update Jest Native docs that it is deprecated

1. Jest Native package will allow for importing existing matchers with legacy prefix, so that users will avoid name clashes on expect function. This will be provided by Jest Native and not the RNTL in order to avoid having to managed that code inside RNTL and to keep it in the final state for potentially long time.