feat: add toBePressed matcher (#203)

[kretajak]

What:

New toBePressed matcher is added

Why:

Closes #203

Checklist:

• Documentation
• Tests
• Updated Type Definitions
• Ready to be merged
  

In my opinion this PR could be followed by another one which would add support for checking aria-pressed="mixed". Maybe toBePartiallyPressed? It would follow the same approach as splitter toBeChecked and toBePartiallyChecked into two separate matchers.

[kretajak]

Hi, may I ask for reviews?

[kretajak]

Hi @gnapse, can I kindly ask for a review?

[gnapse]

Thanks for making this contribution. It is good stuff. Though there are a couple of things that need to be improved.

(the comments marked as "nit-pick" are not fundamental to be changed, but other ones are)

[gnapse]

Suggested change

	This allows to check whether given element has been [pressed](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed).
	This allows to check whether given element is [pressed](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed).

[gnapse]

This test perhaps should be titled "throws an error when element is not a button" because that's the real reason for this use case to fail.

To illustrate, it should fail even if you pass the aria-pressed attribute. So maybe also modify the test to show that:

Suggested change

	test('throws when element do not have aria-pressed attribute', () => {
	const {queryByTestId} = render(`<span data-testid="span" />`)
	expect(() =>
	expect(queryByTestId('span')).toBePressed(),
	).toThrowErrorMatchingInlineSnapshot(
	`Only button or input with type="button" or element with role="button" and a valid aria-pressed attribute can be used with .toBePressed()`,
	)
	})
	test('throws an error when element is not a button', () => {
	const {queryByTestId} = render(`<span data-testid="span" aria-pressed="true" />`)
	expect(() =>
	expect(queryByTestId('span')).toBePressed(),
	).toThrowErrorMatchingInlineSnapshot(
	`Only button or input with type="button" or element with role="button" and a valid aria-pressed attribute can be used with .toBePressed()`,
	)
	})

[gnapse]

nit-pick:

Suggested change

	if (ariaPressed === 'true' || ariaPressed === 'false') {
	return true
	}
	return false
	return ariaPressed === 'true' || ariaPressed === 'false'

[gnapse]

This is mostly it but misses an edge case. An element can have more than one role via the role attribute (ref).

You could soften the condition on the role attribute to check that it includes the button role:

-element.getAttribute('role') === 'button' ||
+element.getAttribute('role')?.split(/\s/)?.includes('button') ||

Though ideally we should do this via the helper functions found in the to-have-role.js source file. Unfortunately, those are internal to the module. They'd have to be moved to a new module role-helpers.js and used from there in that matcher, and in this new matcher.

[gnapse]

nit-pick:

I am not sure why you chose to make these (isButton, isPressed, isValidAriaElement) to be functions. They could simply be variables instead. You compute the value once and store it.

Not a big deal, but just curious.