Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Mouse and Keyboard interface to return Promises #45

Merged
merged 4 commits into from
May 24, 2024
Merged

Update Mouse and Keyboard interface to return Promises #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
431cc5e
Update Mouse tests to expect Promise return
allansson May 23, 2024
e51af7e
Wrap return types of Mouse with Promise
allansson May 23, 2024
a5deca2
Update Keyboard tests to expect Promise return
allansson May 23, 2024
e2b18eb
Wrap return types of Keyboard with Promise
allansson May 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions types/k6/experimental/browser.d.ts
View file
Open in desktop
Copy link
Author

@allansson allansson May 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to find usages in @example tags for all the changes, but I couldn't find any. I figure that I can update them if I find them in subsequent PRs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No worries. There are some usage examples here and here that might help 🤞

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I could have been more clear. I meant that some JSDoc comments include @examples tags and those need to be updated with await, but I couldn't find any using Cmd + F.

Copy link
Member

@inancgumus inancgumus May 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I see. I believe you mean none of the examples have a mouse and keyboard example in their JSDoc comments. It's OK. On a tangent, do you think it would be better if we added some example usages to the mouse and keyboard JSDoc comments (not necessary to do it ATM, but nice-to-have)?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is where I wish we could generate reference docs from the type definitions instead, because having examples in both places would mean us having to keep examples in sync. If the type definitions were the source of truth for the docs, you'd have the same docs in the IDE and on the web.

Copy link
Member

@inancgumus inancgumus May 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be really useful, so we won't have to type k6-docs manually and keep everything in sync.

However, k6-docs examples are more involved, while typescript examples, on the other hand, are small code snippets (does it make sense to add full-blown examples in the typescript comments? I'm not sure).

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is where I wish we could generate reference docs from the type definitions instead, because having examples in both places would mean us having to keep examples in sync

This would be very cool! Would make things simpler for sure.

I usually like to create the simplest example showcasing a typical use case in the type definitions e.g. keyboard.type("Hello World"). In the docs themselves I'd place a full blown working example that can be copy and pasted and ran without any modifications.

Original file line number Diff line number Diff line change
Expand Up @@ -1840,22 +1840,22 @@ export interface Keyboard {
* A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
* @param key Name of key to press, such as `ArrowLeft`.
*/
down(key: string): void;
down(key: string): Promise<void>;

/**
* Dispatches an `input` event with the given `text`.
* This method does not emit `keyDown`, `keyUp` or `keyPress` events.
* @param text Event text.
*/
insertText(text: string): void;
insertText(text: string): Promise<void>;

/**
* Sends a key press message to a session target.
* A press message consists of successive key down and up messages.
* @param key Sequence of keys to press.
* @param options Specifies the typing options.
*/
press(key: string, options?: { delay?: number }): void;
press(key: string, options?: { delay?: number }): Promise<void>;

/**
* Type sends a `press` message to a session target for each character in text.
Expand All @@ -1865,14 +1865,14 @@ export interface Keyboard {
* @param text A text to type into a focused element.
* @param options Specifies the typing options.
*/
type(text: string, options?: { delay?: number }): void;
type(text: string, options?: { delay?: number }): Promise<void>;

/**
* Sends a key up message to a session target.
* A superset of the key values can be found [here](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values).
* @param key Name of key to release, such as `ArrowLeft`.
*/
up(key: string): void;
up(key: string): Promise<void>;
}

/**
Expand Down Expand Up @@ -2078,7 +2078,7 @@ export interface Mouse {
* @param y The y position.
* @param options The click options.
inancgumus marked this conversation as resolved.
Show resolved Hide resolved
*/
click(x: number, y: number, options?: MouseMultiClickOptions): void;
click(x: number, y: number, options?: MouseMultiClickOptions): Promise<void>;

/**
* Shortcut for `mouse.move(x, y)`, `mouse.down()`, `mouse.up()`, `mouse.down()`,
Expand All @@ -2087,27 +2087,27 @@ export interface Mouse {
* @param y The y position.
* @param options The click options.
*/
dblclick(x: number, y: number, options?: MouseClickOptions): void;
dblclick(x: number, y: number, options?: MouseClickOptions): Promise<void>;

/**
* Dispatches a `mousedown` event.
* @param options The mouse down options.
*/
down(options?: MouseDownUpOptions): void;
down(options?: MouseDownUpOptions): Promise<void>;

/**
* Dispatches a `mousemove` event.
* @param x The x position.
* @param y The y position.
* @param options The mouse move options.
*/
move(x: number, y: number, options?: { steps?: number }): void;
move(x: number, y: number, options?: { steps?: number }): Promise<void>;

/**
* Dispatches a `mouseup` event.
* @param options The mouse up options.
*/
up(options?: MouseDownUpOptions): void;
up(options?: MouseDownUpOptions): Promise<void>;
}

/**
Expand Down
44 changes: 22 additions & 22 deletions types/k6/test/browser.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -837,31 +837,31 @@ async function test() {

// @ts-expect-error
keyboard.down();
// $ExpectType void
// $ExpectType Promise<void>
keyboard.down("a");

// @ts-expect-error
keyboard.insertText();
// $ExpectType void
// $ExpectType Promise<void>
keyboard.insertText("a");

// @ts-expect-error
keyboard.press();
// $ExpectType void
// $ExpectType Promise<void>
keyboard.press("a");
// $ExpectType void
// $ExpectType Promise<void>
keyboard.press("a", { delay: 1000 });

// @ts-expect-error
keyboard.type();
// $ExpectType void
// $ExpectType Promise<void>
keyboard.type("a");
// $ExpectType void
// $ExpectType Promise<void>
keyboard.type("a", { delay: 1000 });

// @ts-expect-error
keyboard.up();
// $ExpectType void
// $ExpectType Promise<void>
keyboard.up("a");

//
Expand All @@ -874,47 +874,47 @@ async function test() {
mouse.click();
// @ts-expect-error
mouse.click(0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.click(0, 0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.click(0, 0, { button: "right" });
// $ExpectType void
// $ExpectType Promise<void>
mouse.click(0, 0, { clickCount: 2 });
// $ExpectType void
// $ExpectType Promise<void>
mouse.click(0, 0, { delay: 1000 });

// @ts-expect-error
mouse.dblclick();
// @ts-expect-error
mouse.dblclick(0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.dblclick(0, 0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.dblclick(0, 0, { button: "right" });
// $ExpectType void
// $ExpectType Promise<void>
mouse.dblclick(0, 0, { delay: 1000 });

// $ExpectType void
// $ExpectType Promise<void>
mouse.down();
// $ExpectType void
// $ExpectType Promise<void>
mouse.down({ button: "right" });
// $ExpectType void
// $ExpectType Promise<void>
mouse.down({ clickCount: 2 });

// @ts-expect-error
mouse.move();
// @ts-expect-error
mouse.move(0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.move(0, 0);
// $ExpectType void
// $ExpectType Promise<void>
mouse.move(0, 0, { steps: 10 });

// $ExpectType void
// $ExpectType Promise<void>
mouse.up();
// $ExpectType void
// $ExpectType Promise<void>
mouse.up({ button: "right" });
// $ExpectType void
// $ExpectType Promise<void>
mouse.up({ clickCount: 2 });

//
Expand Down