API proposal: Jest Native matchers migration

[mdjastrzebski]

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.

[MattAgn]

Fully agree with all of the above! I'll try to take one or two tasks when i come back from vacation in a week or so.
Quick naming question: why go for toHaveAccessibleName instead of toHaveAccessibilityLabel or toHaveAccessibleLabel to stay coherent with the prop name?

[pierrezimmermannbam]

That seems perfect! Great work @mdjastrzebski !

[mdjastrzebski]

Update: Jest Native package includes legacy extend as of 5.4.3 🚀🎉

This is not yet publicly documented, that will be done after we complete RNTL matcher migration.

In order to use legacy extend expect(...):

1. Use import '@testing-library/jest-native/legacy-extend-expect instead of import '@testing-library/jest-native/extend-expect
2. Use expect(...).legacy_toXxx matchers instead of expect(...).toXxx.

In the default setup nothing changes, so you need the changed import to enable legacy_toXxx matchers.

[AntoineThibi]

Hello !
I created a PR for toHaveProp matcher : #1477

[hduprat]

Hi everyone,

Here is a PR for the toBeBusy() matcher: #1493

[AntoineThibi]

Hello !

Here is one for the toBeSelected() matcher : #1488