Add a section to explain declarative vs imperative style (Fixes #323) #429
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mlvandijk
reviewed
Dec 27, 2019
There was a problem hiding this comment.
Hi @lisacrispin - I really love this explanation; I think it captures pretty well what we try to say to users.
A few (minor) comments below.
In addition, some suggestions:
- let's see if we can make the wording a little more concise?
- I'd like to add something about imperative steps providing too much detail, making it hard to see what the exact behaviour is that a particular scenario is trying to illustrate. As is decribed in this article
Thanks for taking the time to help out!
…the idea of "pushing the 'how' down"
mlvandijk
requested changes
Dec 29, 2019
There was a problem hiding this comment.
Hi @lisacrispin - I really love this change! Some minor additional suggestions, mainly for consistency with the rest of the docs. (for example, replacing "tests" with "scenarios").
If you agree with my suggested changes, you should be able to click the "commit suggestion" button below each comment and that will automatically apply the suggestion as a commit.
content/docs/bdd/better-gherkin.md
Outdated
|
|
||
| # Consider a more declarative style | ||
|
|
||
| One way to make tests easier to maintain and less brittle is to use a declarative style. Declarative style describes the behaviour of the application, rather than the implementation details. Declarative tests read better as "living documentation". A declarative style helps you focus on the value that the customer is getting, rather than the keystrokes they will use. |
There was a problem hiding this comment.
Suggested change
| One way to make tests easier to maintain and less brittle is to use a declarative style. Declarative style describes the behaviour of the application, rather than the implementation details. Declarative tests read better as "living documentation". A declarative style helps you focus on the value that the customer is getting, rather than the keystrokes they will use. | |
| One way to make scenarios easier to maintain and less brittle is to use a declarative style. Declarative style describes the behaviour of the application, rather than the implementation details. Declarative tests read better as "living documentation". A declarative style helps you focus on the value that the customer is getting, rather than the keystrokes they will use. |
content/docs/bdd/better-gherkin.md
Outdated
|
|
||
| One way to make tests easier to maintain and less brittle is to use a declarative style. Declarative style describes the behaviour of the application, rather than the implementation details. Declarative tests read better as "living documentation". A declarative style helps you focus on the value that the customer is getting, rather than the keystrokes they will use. | ||
|
|
||
| Imperative tests are communicative, and in some contexts, this style of test is appropriate. On the other hand, because they are so closely tied to the mechanics of the current UI, they often require more work to maintain. Any time the implementation changes, the tests need to be updated too. |
There was a problem hiding this comment.
Suggested change
| Imperative tests are communicative, and in some contexts, this style of test is appropriate. On the other hand, because they are so closely tied to the mechanics of the current UI, they often require more work to maintain. Any time the implementation changes, the tests need to be updated too. | |
| Imperative tests communicate details, and in some contexts, this style of test is appropriate. On the other hand, because they are so closely tied to the mechanics of the current UI, they often require more work to maintain. Any time the implementation changes, the tests need to be updated too. |
There was a problem hiding this comment.
Done. Why does the 'and' show up in red there? Is that something I need to change also?
There was a problem hiding this comment.
I don't know. You can ignore it
content/docs/bdd/better-gherkin.md
Outdated
|
|
||
| Imperative tests are communicative, and in some contexts, this style of test is appropriate. On the other hand, because they are so closely tied to the mechanics of the current UI, they often require more work to maintain. Any time the implementation changes, the tests need to be updated too. | ||
|
|
||
| Here's a more imperative style: |
There was a problem hiding this comment.
Suggested change
| Here's a more imperative style: | |
| Here's an example of a feature in an imperative style: |
There was a problem hiding this comment.
Done, and next one I will try to do the "commit changes" thing in the dropdown. Doh.
There was a problem hiding this comment.
Learn something new every day ;)
mlvandijk
changed the title
…es via GitHub review comments.
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
lisacrispin
changed the title
mlvandijk
reviewed
Dec 30, 2019
mlvandijk
reviewed
Dec 30, 2019
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
mlvandijk
reviewed
Dec 30, 2019
mlvandijk
reviewed
Dec 30, 2019
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
Co-Authored-By: Marit van Dijk <mlvandijk@gmail.com>
mlvandijk
approved these changes
Dec 30, 2019
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Working on fixing #323