Best practices about step granularity

[mjoffily]

I would like to get the community's views on best practices about the granularity of the gauge step implementation in Taiko.
I know there probably isn't a "one size fits all" approach, but it would be great to hear how different people in the community are dealing with this.
I am leaning towards granular steps, like below as opposed to coarser steps with more commands inside:
That would increase the re-usability of the steps and get teams up and running faster with just gauge scenarios and less taiko code.

Granular gauge scenario

• Click link "xyz"
• Click button "abc"
• Type "my text"
• Press "Enter"
• Click button and expect popup "mybutton"

mapping to simple taiko implemented steps

step("Click link <linkText>", async (linkText) => {
    await click(link(linkText));
})

step("Click button <buttonText>", async (buttonText) => {
    await click(button(buttonText));
})

step("Click button and expect popup <buttonText>", async (buttonText) => {
    // set alert listener to fail the tests if any alerts are displayed
    let popupAppeared = false
    await alert(async ({message}) => {
        gauge.screenshot();
        gauge.message(`popup appeared with message [${message}]`)
        popupAppeared = true
        await accept()
    });
    await click(button(buttonText));

    assert.ok(popupAppeared == false, "popup appeared but should not have")
})

step("Type <text>", async (text) => {
    await write(text);
})

step("Press <key>", async (key) => {
    await press(key);
})

The challenge I see with this approach is when you need to specify "non-vanilla" attributes, like in the following example where we need to set "nagivationTimeout".

step("Click link <text> and don't wait", async (text) => {
    await click(link(text), { navigationTimeout: 0 });
})

We would need to have different flavors of the same step to cater for these small differences or additions.

Any thoughts as to whether that is a reasonable approach? Would you handle it differently?
Thanks for any feedback you can provide.

[zabil]

This is subjective. But as a rule of thumb, avoid direct granularity. In the example

step("Click button <buttonText>", async (buttonText) => {
    await click(button(buttonText));
})

A step maps directly to an action on the screen. This can make specifications hard to read and verbose.

A specification must add value by describing intent. A specification for searching Google could look like

# Search internet
* Search google for "test automation tools"
* Check if "Gauge" is listed

with steps

step("Search google for <query>", async (query) => {
    await goto('google.com');
    await write(query);
    await click ('Google Search');
});

step("Check if <item> is listed", async (item) => {
    assert.ok(await text(item).exists());
});

Here, the intent is to search Google and verify search results. The specification and it's implementation are quite different. This makes your test suites less verbose and maintainable.