Fix and add unit tests for Caps Word to work with Unicode Map, Auto Shift, Retro Shift.

[getreuer]

This PR fixes Caps Word to work correctly with Unicode Map, Auto Shift, and Retro Shift, and adds unit tests.

Description

Caps Word currently does not work correctly with Unicode Map, Auto Shift, and Retro Shift:

• With Unicode Map pairs XP(a, A), it should be possible to handle these keycodes in caps_word_press_user() such that they are shifted. But currently, Unicode Map's handler runs before Caps Word, and Caps Word does not see the event.

• When Auto Shift is enabled for letter keys, they should be shifted when Caps Word is on regardless of whether they are released before AUTO_SHIFT_TIMEOUT, but currently they are not. Similarly for Retro Shift.

This PR is:

1. @kosorin's Fix Caps Word and Unicode Map #17247, which fixes Caps Word to work with Unicode Map. Incidentally, it also fixes Caps Word to work with Auto Shift and Retro Shift, which currently do not work correctly as @qyurila noted in Fix Caps Word not working with Auto Shift and Combo feature #17240.

2. Unit tests to verify that these features now work together.

Types of Changes

• Core
• Bugfix
• New feature
• Enhancement/optimization
• Keyboard (addition or update)
• Keymap/layout/userspace (addition or update)
• Documentation

Checklist

• My code follows the code style of this project: C, Python
• I have read the PR Checklist document and have made the appropriate changes.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• I have tested the changes and verified that they work and don't break anything (as well as I can manage).

[KarlK90]

Thanks for you contribution and also that you came back and added more unit-tests! Really appreciated. I have some recommendations on moving the convenience test helpers into base classes to make them universally accessible for other unit-test but apart from that you have my approval.

[getreuer]

@KarlK90 thank you for the suggestions! I added some new test utilities to this PR: EXPECT_REPORT, EXPECT_UNICODE, tap_key(), and tap_keys(). (Let me know if you had a different direction in mind.)

I went ahead and applied them to most tests. Particularly the EXPECT_REPORT macro is frequently useful and makes a nice reduction in boilerplate in many tests.

Here is a description of the utilities (also documented in the code):

• EXPECT_REPORT sets a gmock expectation that a given keyboard report will be sent. For instance,

  EXPECT_REPORT(driver, (KC_LSFT, KC_A));

  is shorthand for

  EXPECT_CALL(driver,
    send_keyboard_mock(KeyboardReport(KC_LSFT, KC_A)));

• EXPECT_UNICODE sets a gmock expectation that a given Unicode code point will be sent using UC_LNX input mode. For instance for U+2013,

  EXPECT_UNICODE(driver, 0x2013); 
  

  expects the sequence of keys: "Ctrl+Shift+U, 2, 0, 1, 3, space".

• tap_key(key) is a TestFixture method that taps a given KeymapKey, optionally with a specified delay between press and release.

• Similarly, the method tap_keys(key_a, key_b, key_c) taps a sequence of KeymapKeys.

[KarlK90]

@getreuer Those facilities and changes to the tests are very nice indeed! Improving the ergonomics for writing these tests is one of my long term goals and this is a step in the right direction.

While reading the changes to the unit tests I noticed that we have two more frequent use-cases that we expect:

• empty reports EXPECT_REPORT(driver, ());
• making sure that no reports are send EXPECT_CALL(driver, send_keyboard_mock(_)).Times(0);

These can easily be added by providing these macros as well:

#define EXPECT_EMPTY_REPORT(driver) EXPECT_REPORT(driver, ())

#define EXPECT_ANY_REPORT(driver) EXPECT_CALL((driver), send_keyboard_mock(_))

#define EXPECT_NO_REPORT(driver) EXPECT_ANY_REPORT(driver).Times(0)

I have them in a working condition in my local branch, it juts needs some clean-up and documentation. If you like/don't mind I can go ahead and push them to this PR.

[getreuer]

@KarlK90 Yes, please go ahead and push into this PR! =)

Those are great additions. Not only is it more concise, but the meaning of EXPECT_ANY_REPORT(driver) is more readable and obvious than

EXPECT_CALL(driver, send_keyboard_mock(_));

[KarlK90]

@getreuer Done! I amended the changes to you commits and changed the commit messages. I took the liberty to convert the documentation comments to doxygen, but left them untouched otherwise. Expect for the empty report example in EXPECT_REPORT.

[getreuer]

@KarlK90 Awesome! This all looks good. It is fine by me to merge this PR whenever the maintainers would like to do so.

[KarlK90]

Now also on the develop branch 🎉