This project is read-only.

Level of details

May 2, 2011 at 8:03 AM
Edited May 2, 2011 at 8:15 AM

Hi, I've got the following story and scenario.

Story is User sign up into site   
  In order to sign up into Site
  As a website user I want to get access to the web application With scenario Happy Path Given I provide the correct optional first name And I provide the correct optional last name And I provide the compulsory email which is not already in the system And I enter the correct compulsory Captcha And I agree or not to being sent promotional material And I confirm the terms and conditions have been read When I click on the sign up button Then the I get redirected to the sign up success page

My first question is what criticisms anyone might have of the story and scenario as I've just written it. I know it's a "how long is a piece of string" question but as a beginner, I would like to be guided a bit and not stray off too much.

The second question I have is this:

The scenario as it is, will, in my opinion, be suitable for the client to read and understand. However, when the conversation is between the analyst and the development team, there needs to be more detail. For instance, I've got:

Given I provide the correct optional first name

the developer will probably come back and ask, "What do you mean correct first name?". That's a valid question and I could create another document to flesh this out. However, it's something that I'd rather not do because that will mean that there are too many documents to maintain and it might go against the testable part of the INSPECT principles for writing a user requirement.

So my questions are:

  1. Is this the right place to put that level of detail?
  2. If so, is there a possibility to hide some of the details from the client but shown to the developer? For instance, there are situations where jargon can pollute the requirement from the client's perspective but that jargon is needed by the developer.
  3. If not, how have you dealt with communicating, recording and maintaining requirements that developers can work from?

TIA,

David

Coordinator
May 2, 2011 at 8:55 PM

This is a pretty typical dilemma for first time BDDers (or me when I started at least)

Personally, I would use the actual first name in the step. You've already said that the scenario is the happy path, so if you had

 I want to get access to the web application   
      With scenario Happy Path   
        Given I enter the first name "Rob"
          And I enter the last name "FE" 

Then that would be easier to reuse than before with the ultra-descriptive method names, and could possibly make more sense to a business analyst (because what defines "correct"?)

Instead of 

          And I provide the compulsory email which is not already in the system 

I would go with

          And I provide the email "me@email.com" 

Later, when you wanted to test that emails were unique you could have

          Given someone else has signed up with the email "me@email.com"
	 When I provide the email "me@email.com"

In terms of hiding detail, one thing I've found useful is aggregating steps. For example, you could create a new method called "AValidLogin()" in which you call each of the given methods (directly) that you gave in your example. That way, the "happy path" scenario will be able to describe exactly what a valid login is, but then subsequent scenarios can "abbreviate" that into a single step. Does that make sense?

StoryQ is all about communication, recording and maintaining requirements for developers to work from :). Don't be afraid to just get stuck in, it's relatively easy (and definitely recommended) to refactor as you go (Note that the text converter is meant to be a once-off thing: StoryQ users maintain C#. If you want to maintain text files then specflow is excellent, but you don't get refactor support ;) ).

Does that help?

Finally, why not show this text (maybe as the output from a test run) to a real user / BA? BDD is all about having a common language...

-Rob

 

 

May 2, 2011 at 9:53 PM
> Finally, why not show this text (maybe as the output from a test run) to a real user / BA?

In my shop, the StoryQ report is integrated into a TeamCity report tab and this is what the BA uses to sign off a feature a 'done' / 'ready for QA'.

Worth considering integrating into your development process.

On 2 May 2011 20:55, robfe <notifications@codeplex.com> wrote:

From: robfe

This is a pretty typical dilemma for first time BDDers (or me when I started at least)

Personally, I would use the actual first name in the step. You've already said that the scenario is the happy path, so if you had

 I want to get access to the web application   
      With scenario Happy Path   
        Given I enter the first name "Rob"
          And I enter the last name "FE" 

Then that would be easier to reuse than before with the ultra-descriptive method names, and could possibly make more sense to a business analyst (because what defines "correct"?)

Instead of

          And I provide the compulsory email which is not already in the system 

I would go with

          And I provide the email "me@email.com" 

Later, when you wanted to test that emails were unique you could have

          Given someone else has signed up with the email "me@email.com"
	 When I provide the email "me@email.com"

In terms of hiding detail, one thing I've found useful is aggregating steps. For example, you could create a new method called "AValidLogin()" in which you call each of the given methods (directly) that you gave in your example. That way, the "happy path" scenario will be able to describe exactly what a valid login is, but then subsequent scenarios can "abbreviate" that into a single step. Does that make sense?

StoryQ is all about communication, recording and maintaining requirements for developers to work from :). Don't be afraid to just get stuck in, it's relatively easy (and definitely recommended) to refactor as you go (Note that the text converter is meant to be a once-off thing: StoryQ users maintain C#. If you want to maintain text files then specflow is excellent, but you don't get refactor support ;) ).

Does that help?

Finally, why not show this text (maybe as the output from a test run) to a real user / BA? BDD is all about having a common language...

-Rob

Read the full discussion online.

To add a post to this discussion, reply to this email (storyq@discussions.codeplex.com)

To start a new discussion for this project, email storyq@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe or change your settings on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com


May 3, 2011 at 8:09 AM

Hi Rob,

Thanks for your answer. I am indeed getting stuck in but as a lot of eyes are on me for direction, I thought I'd get an idea about how other people have dealt with the issue that I mentioned. I think I've got your point about the refactoring and I'll give it a go.

David

May 3, 2011 at 8:15 AM
damianh wrote:
> Finally, why not show this text (maybe as the output from a test run) to a real user / BA?

In my shop, the StoryQ report is integrated into a TeamCity report tab and this is what the BA uses to sign off a feature a 'done' / 'ready for QA'.

Worth considering integrating into your development process.

Hey Damian,

We have also got TeamCity as our CI tool of choice although we're very inexperienced at it. I've managed to get the server going, run some unit tests and show the code coverage. However, I wouldn't really know where to start to add the report tab and publish the results of the stories and scenarios. Any hints on how to do that would be very much appreciated.

David

 

Coordinator
May 3, 2011 at 11:46 AM

Read this email on top of Rob's suggestions. Here's are some extra comments:

  • Rob's point is to separate data in the Acceptance Criteria (note: I am using the language from Continuous Delivery by Humble & Farley in Chapter 8) so that it passed into the Test Implementation Layer and that you create a better sense of a DSL. 
  • What I would be looking for in the Application Driver Layer are for clarity of abstractions around User and validations and then collaborations between objects (how do you move between "button click" and "new page"). Now it seems to me that you are tied to UI Driver type implementation. I could write this code quite differently that might satisfy an API rather than say a browser. I don't think the API would have a "button" and new page.
  • My experience has been that the login mechanism is a very hard place to start learning this approach - start will real workflow and drive out domain concepts - If you want to see a great BDD-style testing on login/authentication there is a ruby on rails plugin (mmm ... act_as_authenticated ... perhaps, that was 3 years ago) that it is one great example.
  • I have talked this in other places - I do test-last development with these tests. I write the Acceptance Criteria first, do unit and integration tests and then complete Test Implementation Layer. Freeman and Pryce in Growing Object Oriented Systems (chapter 1 & 2) cover this nicely. They talk about using acceptance criteria as a measure of progress rather than for regressions. This relates to your communication of progress.
  • if you have people who are going to sign these off, ensure they are part of writing them in the first place. I have found that in a couple of hours, I have even been able to get analysts to write the stories so that they are parsed in the GUI app. I find that the original stories will always morph but the faster you turn them around the better for those that wrote them in the first place.

I hope these comments give you some leads for further reading. Personally, I find the creating and reviewing with analysts, business and testers over-hyped (I'm in NZ) - it falls off very quickly. However, that might be because the teams I work on get working versions out early to drive out missing things and then deliver very few defects. User stories just help us get to the code quicker and then as devs allow us to have move conversations with our code by ourselves! Now I'm sounds insulated ;-)

Coordinator
May 3, 2011 at 11:53 AM
We have also got TeamCity as our CI tool of choice although we're very inexperienced at it. I've managed to get the server going, run some unit tests and show the code coverage. However, I wouldn't really know where to start to add the report tab and publish the results of the stories and scenarios. Any hints on how to do that would be very much appreciated.

Team City allow you to archive artifacts, it is in one of the configuration settings and you enter in a wildcard. You need to point it at the test folder that the report is exported to.

http://www.jetbrains.com/teamcity/features/build_management.html#Artifacts

http://blogs.jetbrains.com/teamcity/2010/02/26/artifact-packaging-with-teamcity/

http://stackoverflow.com/search?q=teamcity+artifacts

May 3, 2011 at 2:22 PM

Hey Todd,

There seems to be a lot of reading that I have to do. Thank you for your advice on how to integrate the report in TeamCity. After a bit of digging, I've been able to get things going. Just a bit more details on how to do this in TeamCity 6.0.3:

 

  1. Within "general settings" of the "Configuration steps", add the artifact path: %teamcity.build.workingDir%\sourceFileOrFolder=>Outputfolder
  2. Then go to "Administration --> Server Configuration", Click on the "Reports tab".
  3. Create a new report tab
    1. "Tab title" is self explanatory
    2. Base path - This is the output folder specified in step 1 i.e. Outputfolder
    3. The start page is the report file. In my case it is StoryQ.xml
May 6, 2011 at 9:34 AM
Yep, this is how we do it.

Worth adding this to StoryQ wiki documentation?

On 3 May 2011 14:22, davidsiew <notifications@codeplex.com> wrote:

From: davidsiew

Hey Todd,

There seems to be a lot of reading that I have to do. Thank you for your advice on how to integrate the report in TeamCity. After a bit of digging, I've been able to get things going. Just a bit more details on how to do this in TeamCity 6.0.3:

  1. Within "general settings" of the "Configuration steps", add the artifact path: %teamcity.build.workingDir%\sourceFileOrFolder=>Outputfolder
  2. Then go to "Administration --> Server Configuration", Click on the "Reports tab".
  3. Create a new report tab
    1. "Tab title" is self explanatory
    2. Base path - This is the output folder specified in step 1 i.e. Outputfolder
    3. The start page is the report file. In my case it is StoryQ.xml

Read the full discussion online.

To add a post to this discussion, reply to this email (storyq@discussions.codeplex.com)

To start a new discussion for this project, email storyq@discussions.codeplex.com

You are receiving this email because you subscribed to this discussion on CodePlex. You can unsubscribe or change your settings on codePlex.com.

Please note: Images and attachments will be removed from emails. Any posts to this discussion will also be available online at codeplex.com


May 6, 2011 at 2:06 PM
robfe wrote:

StoryQ is all about communication, recording and maintaining requirements for developers to work from :). Don't be afraid to just get stuck in, it's relatively easy (and definitely recommended) to refactor as you go (Note that the text converter is meant to be a once-off thing: StoryQ users maintain C#. If you want to maintain text files then specflow is excellent, but you don't get refactor support ;) ).

Does that help?

Finally, why not show this text (maybe as the output from a test run) to a real user / BA? BDD is all about having a common language...

-Rob

 

 

Hey Rob, we've just gone through StoryQ with the client and developers. The client loved it as it makes his life so much easier and the developers liked it to. However, my current concern has been brought up by the technical director. The point is that the latter would like to have documentation so that someone new could pick up what defines a correct optional first name from the following:

Given I provide the correct optional first name

Yes I can aggregate that business logic in the code but that would mean that would pose serveral problems for a non technical user. Maybe I could do what I want using SpecFlow but StoryQ is much nicer and so much easier to use. The compromise we've reached is that currently we'll be putting that business logic in the code as our client is fairly technically minded. However, I believe it would be a nice feature to provide and would significantly enhance StoryQ. For instance, we could write the business logic within the story itself. However, if that goes against convention, we could write the business logic in the code in a certain place e.g. in the summary of each method and then StoryQ would parse the code and output that business logic in the report generated. Let me know what you think about the idea.

Regards,

David

PS: My team members have agreed to the translations in Russian and Estonian although time is the issue. I'll try and get the French one done this weekend if possible and I'll get you the other translations when we can.

 

 

 

May 13, 2011 at 9:41 PM
robfe wrote:

Personally, I would use the actual first name in the step. You've already said that the scenario is the happy path, so if you had

 I want to get access to the web application   
      With scenario Happy Path   
        Given I enter the first name "Rob"
          And I enter the last name "FE" 

Two thoughts:

1. This scenario loses the fact that the name is optional. One could create a second happy-path scenario to capture that case, or one could lobby for introducing the dreaded "or" statement :-).

2. Would it make sense to express name "correctness" as its own scenario? Something along the lines of

  •    Scenario valid first name
  •    Given a name entry box
  •    When I enter a name
  •    Then the system should only accept it if it follows the form of ...

I understand the "it follows the form of ..." can get absurdly long, as it's essentially a regular expression, but this scenario does capture a general requirement that can show up many places (any place you have to enter a name). It also satisfies the technical director's request for detailed specs.