Make it easy to pass keys to keyboard event triggers

[egil]

The current keyboard event triggers require you to pass the explicit key as a string you want, e.g. cut.Find("input").KeyPress("a"). That works ok for normal characters, but for keys like "backspace" it can be confusing to the user.

To make it easier, we should investigate having a helper class, type, or enum, that provides the values, so we avoid the "magic strings" in the test code. E.g.:

cut.Find("input").KeyPress(Key.Enter);
cut.Find("input").KeyPress(Key.Backspace);
cut.Find("input").KeyPress(Key.A);
cut.Find("input").KeyPress(Key.a); // difference between lower case and upper case letters?

[DarthPedro]

This would be great for people new to the bUnit library. It would definitely make it more accessible and other test libraries, like Selenium have a Keys class for doing this.

It is difficult to find the documentation of the special keys (without asking someone), and they are useful in testing input controls. Backspace is a relatively easy one to figure out, but whether it's Up, UpArrow, or ArrowUp is more complicated.

[egil]

Cool. Great tip with Selenium, could definitely draw some inspiration from them.

Btw., I accept pull requests if you want to give this a shot @DarthPedro, and I repay with nitpicky code reviews :-)

[DarthPedro]

I may be able to find some time to help build that into bUnit. It probably won't be for a couple of weeks though. And, I'm really good at ignoring comments. ;)

I didn't see a Contributing.md file so not sure if there are any particular steps to follow.

[egil]

Ahh yes, I need to add one of those Contributing.md files. I actually have an issue for that #97 ...

Anyway, the basic guidelines is to use C# 8, follow the general asp.net core framework coding guidelines and create a pull request that targets the DEV branch.

But it would also be super helpful if you could help brainstorm what the API should look like.

[DarthPedro]

I can handle those guidelines. :) I'll make the change.

I think the API should only be for special characters. It should be a static class with static properties for each special key, like:

    public static class Keys
    {
        public static string Backspace { get; }
        ...

Then in a test you would use it as follows:

    element.KeyPress("z");               // for text keys
    element.KeyPress(Keys.Backspace);    // special keys

[egil]

I think the API should only be for special characters...

I think makes sense, since there are a lot of characters in many languages. I do wonder if the text keys should be changed to the char type instead of string? I think that it is only the special keys like backspace, up, etc., that consist of more than one character?

Have you considered the alternative to a static class, e.g. an enum? Then there could be a dedicated overload to the KeyPress method that takes the enum instead of a string. That might make the SpecialKey enum more discoverable by users?

[DarthPedro]

@egil Your questions made me remember something. .NET already has an enum definition for Keys. However it's in the System.Windows.Forms namespace and assembly (https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.keys?view=netcore-3.1). I'm not sure if you want to add that dependency to bUnit, but we can certainly use the design.

[egil]

It looks as if that enum contains more options than we should need for this purpose, so I think a custom for bUnit is preferred.

[DarthPedro]

Yes, that makes sense. I will create a custom enum with only special keys for bUnit. Then update the KeyPress, KeyUp, KeyDown methods with overloads which take that enum. Does that sound like a plan?

[egil]

Sounds able right. I think it needs to be an overlead that replaces thekey argument in this method: https://bunit.egilhansen.com/api/Bunit.KeyboardEventDispatchExtensions.html#Bunit_KeyboardEventDispatchExtensions_KeyDown_IElement_System_String_System_String_System_Single_System_Boolean_System_Boolean_System_Boolean_System_Boolean_System_Boolean_System_String_

[DarthPedro]

Right. The Keys enum would overload the string key parameter in those extension methods.

[egil]

Hey @DarthPedro, should I officially assign this to you?

[DarthPedro]

Yes, I was looking at what I could work on next. This looks like a good one since we already talked through the design. Assign it to me.

Do you have any changes to the design discussion above?

• Enum of special keys.
• Overload methods in KeyboardEventDispatchExtensions methods to support special keys.
• Tests for these methods.
• Update docs on sending keys.

[egil]

Sounds good. Can't think of anything else.

[egil]

Hey @DarthPedro, just going through all issues and you were interested in this, so I took the liberty and assigned it to you. If you want to do it just let me know.

[egil]

Hey @DarthPedro, just an FYI, @duracellko beat you to it.