[QA] Standardize Naming Conventions for Step Definition Functions in E2E Test Specs

[anon-pradip]

Description

In our E2E test suite (specifically in *.spec.ts files), we have step definition functions that are used in test scenarios. However, the naming patterns are inconsistent, making it hard to distinguish them from regular helper functions. This leads to confusion during code reviews, maintenance, and onboarding.

Current Inconsistencies

We currently use two main approaches, loosely aligned with BDD Given/When/Then grammar:

1. Prefixed with "user" (e.g., past-tense or "has" form): These represent "Given" or setup steps and are grammatically consistent within this category.

   • Example: await api.userHasBeenCreated({ ... })
   • Example: await api.userHasCreatedFolder({ ... })

2. Without "user" prefix (e.g., imperative or action-based): These represent "When" or action steps.

   • Example: await ui.logInUser({ ... }) (imperative, present tense for action)
   • Example: await ui.logOutUser({ ... })

The inconsistency lies in the inconsistent use of the "user" prefix: Given steps consistently use it, but When steps do not, leading to a mix that doesn't align well across the BDD structure.

Questions for Discussion

• Prefix Usage: Should all step definitions be prefixed with "user" (e.g., userHasDeletedProjectSpace) for consistency in both ui.* and api.* modules? For example, we could use api.userHasBeenLoggedOut or ui.userHasBeenLoggedOut.
• Tense and Form: For "Given" steps (setup), should we use past tense like userHasLoggedIn or present like userLogsIn? For "When" steps (actions), imperative like logInUser seems fine, but is there a better pattern? Grammatically aligning with Given/When/Then could mean present tense for When (e.g., userLogsIn instead of logInUser) to match the action-oriented nature.
• Distinguishability: How can we ensure step definitions are clearly distinguishable from helper/utility functions (e.g., via naming, location, or documentation)?
• Examples to Consider:
  • Current: export async function deleteGroup({ ... }) → Should it be export async function userHasDeletedGroup({ ... }) or export async function deleteGroupForUser({ ... })?
  • Current: ui.logInUser → Should it be ui.userLogsIn (present tense for When) or keep as-is?

Proposed Goals

• Establish a consistent naming pattern across api.* and ui.* step definitions.
• Align with BDD principles (Given/When/Then) where possible.
• Improve readability and reduce ambiguity in test code.

Additional Context

• This affects files in the tests/e2e-playwright/steps/ directory.
• Related to our testing framework (Playwright).
• No breaking changes needed yet; this is for future consistency.

Please share your thoughts, suggestions, or examples from similar projects. Let's aim for a pattern that scales well!

[anon-pradip]

#13454 (comment)

[individual-it]

CC @phil-davis any thought?

[saw-jan]

My opinions:

• For API steps (api.<function>): userHasShared..., userHasBeenCreated, userHasAssignedToRole - not mentioning admin for admin actions. All API steps should be treated as Given steps.
• For UI steps (ui.<function>):
  • Actions (When steps): userShares..., userNavigates
  • Assertion (Then steps): ...should<Be|Have|Not|....>.... but some when actions do the assertions within the function which is fine.

[saw-jan]

@LukasHirt we would like to hear your opinion on this