Cucumber test - feature file & test code format

Mohammer5 commented 4 years ago

Right now we don't have any rules in place for how to write and format our feature files.

We've already decided that we don't want the name of the files to represent the feature text in ui-core, but apart from that, there has been no other decision made and it'd be nice to have a consistent style across repositories

Current inconsistencies

Steps are written from different perspectives

In ui-forms they're written from the perspective of the user, e. g. "When the user clicks ...". In ui-core they're more abstract, e. g. "When the Checkbox is checked".

I'm in favor of leaving the user out as the normally shortens the step definition in my experience

Scenario descriptions from the user's perspective

Just like with the step definitions, these can be written from the user's perspective or not.

Unlike the step definitions, these read quite nicely when written from the user's perspective.

I've also noticed that a test wasn't working when the scenario's description was identical to a step definition. Sometimes it's nice to have the same scenario description as the "When" step:

Scenario: The user selects the first option
  Given a select is rendered
  When the user selects the first option
  Then the select's value is "foo"

If we exclude the user from step definitions, but allow the user to be included in the Scenario, it'd work:

Scenario: The user selects the first option
  Given a select is rendered
  When the first option is selected
  Then the select's value is "foo"

Grouping steps

We could group step definitions by scenario or by step type (Given, When, Then). Currently they're mostly grouped by step type (I think I grouped them by scenario somewhere, but don't remember where)

Indentation

The way we indent feature files is consistent across our repositories, but there are alternative ways. And we simply haven't talked about what we want:

Current indentation

Feature: The user bla bla

  Scenario: The user does something
    Given some background
    And some other stuff as well
    When something happens
    Then somthing clearly happened

Alternative

Feature: The user bla bla

  Scenario: The user does something
    Given some background
      And some other stuff as well
     When something happens
     Then somthing clearly happened

Storybook story organisation

Right now all stories are just inside the stories folder. I think @ismay suggested at some point we put them into folders, which I suppport as well, e. g:

| stories/
|--- docs/
|------ Checkbox.stories.js
|--- testing/
|------ Checkbox.testing.js

cooper-joe commented 4 years ago

Thanks @Mohammer5 for bringing this up.

In ui-forms they're written from the perspective of the user, e. g. "When the user clicks ...". In ui-core they're more abstract, e. g. "When the Checkbox is checked".

I'm in favor of leaving the user out as the normally shortens the step definition in my experience ... If we exclude the user from step definitions, but allow the user to be included in the Scenario, it'd work

Good point that we should have a consistent perspective. I am also in favor of leaving the user out of step definitions and keeping step definitions objective. I think including the user in a scenario description works well where the component is user facing. However, I don't think the user should be a required part of a scenario and/or feature description. (I don't think you're saying this, but just to be clear)

Indentation

The way we indent feature files is consistent across our repositories, but there are alternative ways.

I am happy with the way we indent now. I think the step titles (given, when, then etc.) are part of the sentence and are read as a whole. When I read scenarios it makes sense to scan them with an aligned left vertical line. This is not something I feel strongly about, so I can be convinced otherwise.

ismay commented 4 years ago

Storybook story organisation

Right now all stories are just inside the stories folder. I think @ismay suggested at some point we put them into folders, which I suppport as well, e. g:

| stories/ |--- docs/ |------ Checkbox.stories.js |--- testing/ |------ Checkbox.testing.js

Actually what I meant was that I'd prefer to have all the stories that are used for testing completely separate from the stories used for docs. I don't think the tests are very suitable for docs, which to me have a slightly different purpose (demonstrate to a dev how it works and looks). I've already seen tests breaking because of a change in the docs that didn't relate to the tests. Though maybe there's an argument to be made for using the docs since that'd be more realistic in a way? I do think that that'd lead to very repetitive and less useful docs.

I was thinking of just using the .testing file extension for separation, but I like separating them by folder as well even better. Makes it even more clear, so I'm in favor of that 👍. I think it'll increase the reliability of our tests.

Steps are written from different perspectives, Scenario descriptions from the user's perspective, Grouping steps

I think that maybe there'll also be a difference between our apps and libs like ui-core because the use-cases are a bit different? I can imagine for an app the tests will be more high-level because you're directly testing what a user wants to do in the app. Whereas with ui-core we're testing small parts of a UI. Maybe they can be worded the same, I don't know.

I have to say that this is not that big of a concern for me. I would just prefer to have an environment that makes it very easy to add and update tests, so that the barrier to adding and maintaining them is as low as possible. If having a more strict convention on test style helps with that I'm all for it 👍. As long as it doesn't get cumbersome or annoying to work with.

dhis2 / notes