getting the balance right between SBEs and other product documentation - bdd

Reading online material (e.g. Fowler, Gerard), it seems that Specification By Example stories should not be complete specifications of functionality.
Question 1: How does one starting off with SBE's decide how comprehensive their stories need to be in terms of describing all of the functionality of a system? I.e. when can I stop writing stories because I have captured enough?
Question 2: In an organisation where test teams verify products against the product documentation, if the stores are not a complete specification, am I correct in thinking that 'other' product documentation needs to contain all the cases that are not covered by the SBE's?

Regarding question 1:
The most important part of developing any system is that the development team has a conversation with the product owner. First find out the crux of the feature which they require. I'll answer this question by working through an example; let us say that the product owner may want a facility to login to their new website. This requirement could be written as:
In order to gain access to the website's facilities
As a user
I want to be able to login to the website
(Note that I'm using the Gherkin domain specific language for writing the scenarios and features in this answer)
With the product owner's key requirement specified, you should now discuss with them how you think this feature should be implemeneted from a users perspective (keep it high-level, don't use technical jargon, discuss with the business to find out what they want). So the first "happy path" scenario you might identify could be:
Given a user is on the login screen
When they submit valid login credentials
Then they gain access to the main website
After further discussion with the product owner they tell you that as the website contains extremely sensitive information, and that any failed log-in attempts should be reported to a system administrator. This would result in another scenario:
Given a user is on the login screen
When they submit invalid login credentials
Then the system administrator is informed of the failed log-in attempt
And the user is informed that their login attempt failed
At this point the product owner might say that these are the only scenarios they want for logging into the system. So from the development teams perspective no more investigation would need to be done regarding this feature (so you wouldn't need to write any more user stories). Sure, at a later point in the projects development, the product owner might also tell you that they'd like to inform a user when they last logged into their site before reaching the main website, but you'd only need to worry about this when they ask for it.
Regarding question 2:
The organisation should be verifying the products against "living" documentation e.g. using Cucumber(for example) which generates tests from the scenarios detailed above.
Also as I said in the answer to question 1, you should identify "just enough" of the scenarios/use cases to satisfy the product owner. What the product owner asks for is the complete specification. Don't try and second guess what the product owner might want because this may result in be a classic case of YAGNI.

Related

Ruby on rails 4 - What would be the best way to allow one user to see the data of another user

I want to allow one user on my app to chose who can see his own data, I don't know if I'm really clear so here is an example :
User A creates data on a table and he can only see his own data and/or decide to share it with another user.
User B can only see the data from another user that allowed him to do so.
I was thinking of some random token generated when the user is created and then the user can decide to share this token with someone else and then display the data based on this token?
It really depends on your "business rules" here. For instance, in an application I developed read rights were based on "privacy levels". Privacy level 0 meant that only you can view the data whereas privacy level 1 denoted that anybody could view the data. All of my queries were tailored to that datapoint, and a model relation to the user denoted the "owner."
So in your scheme, you propose a system where each record has it's own permission token, much like the system used in Google docs. This is a totally valid way of sharing records in a system. You could also get much more complex by allowing users to add users to the record, which might be another optimal solution for your use case.
Anyway, those are just a few thoughts on the subject. Let me know if that helps.

How do describe a simple process in Gherkin-style? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Suppose I'm designing some SaaS service. And I need to have a function that allow users create sites. User can makes special settings for each site in the admin panel (e.g. design of widget) and gets unique code for install service to his own site.
User story could be:
As a logged user I want to add the new site in the admin panel so that I could configure each instance of widgets separately and could get a unique code for install widget to my own site.
Form
But if I will try to describe this functionality with BDD or GWT (Given When Then) or Gherkin-style, I will face with some trouble. I start from next description:
GIVEN I'm logged into admin panel
AND I'm on "Sites" page
WHEN I click "Add site" button
THEN Pop-up window "Add site" come up
As you can see above realization suppose that site adding will be in pop-up window (e.g. it very important for UX). Pop-up window contains Site URL input field, drop-down control with languages and "Add" and "Cancel" buttons.
And we got a strange scenario which responsible for just pop-up opening. Is it correct? And how can I name this scenario ("Add site's form opening" ??)? Also this scenario has only a one case (when I click - pop-up open). Maybe this scenario not needed at all? I'm confused...
In this case we need to create another scenario when describes:
GIVEN "Add site" pop-up form is opened
WHEN I fill the "Site URL" field
AND click on "Add" button
THEN New site will be create in system
AND I will transfer to my own site's list
How do you think, where do I need to apply a business rules such as:
1) When new site is created a unique code must be generated and consist of minimum 8 characters including numbers and Alphabetical symbols.
2) checks doesn't apply for Site URL input field and user can input a Cyrillic symbols
3) etc?
I have a lot of additional question and hope on the community help!
The thing with BDD is to stay away from implementation details as much as possible. This scenario has multiple implementation details:
GIVEN I'm logged into admin panel AND I'm on "Sites" page
WHEN I click "Add site" button
THEN Pop-up window "Add site" come up
What happens if the "Sites" page becomes "Awesome Site" page or is simply deleted?
What happens if "Add site" is not a button anymore?
What happens if it's not a popup but a redirect occuring
What happens after? Is the value simply in showing the popup? I guess not...
For this specific example, a better approach would be:
GIVEN I'm an authorised administrator
WHEN I enter all the required information for a new site and save it
THEN I should see that site in my own sites list
With this scenario, if your implementation changes, you will only have to change your step definitions, you won't have to change your gherkin. Don't forget that those tests are supposed to explain the Behaviour of the system, not the way it is implemented.
The other questions you have are more related to unit testing in my opinion:
When new site is created a unique code must be generated and
consist of minimum 8 characters including numbers and Alphabetical
symbols => I'd do it at the class level, gherkin would not be
appropriate unless the customer specifically asked for this, then
the condition is "THEN a code having the required characteristics is
generated for that site" and you would have to define "required
characteristics" in a glossary the customer can read and understand.
Checks doesn't apply for Site URL input field and user can input a Cyrillic symbols => again, would put that at the class level en same as for 1. unless the customer wants to be able to read something about it, it should be at the unit level.
I hope that answers your question. I recommend this article by Dan North if you want to have a better idea of how to write better gherkin features.
EDIT 11/13/14
Based on your comments, I suggest we take a step back and describe a way to deal with requirements in your case. I have to tell you that I'm not a BDD expert and am only sharing my own personal experience, for more info on the subject I suggest you get in touch with the guys behind BDD Kickstart and Cucumber.pro where you will find online BDD courses. They will be able to give you lots of information and books to read.
That being said, let's dive into the subject.
The first thing you get is a list of features or stories that, if you follow Mike Cohn's story template would look like:
As a <type of user> I want <to do something> in order to <serve a business purpose>
I personally like to put the business purpose first to make sure we don't skip it in the discussions. You might also not follow that template and that's fine, but remember that it's a good idea to make sure the features you are listing with your customers have a business purpose. If there is no business value behind a feature then what's the point of doing it anyway...
So you do have a list of features/stories described as above. Now for each of these features, there are different cases or scenarios, that's what Dan describes in his article. This is where the Given-When-Then is introduced.
Scenario: Title
Given <some context>
When <there is an event>
Then <something happens>
Each of those scenarios are examples on how this specific feature behaves in different contexts. They are the different acceptance criteria for a specific feature, things the customer described as the expected behaviour of the system. They should be ignorant of any implementation details. So stuff like:
Given I am on page "First page"
When I click "Hello world"
Then I should see "You clicked hello world"
Is wrong for the reasons described prior to this edit.
Let's assume the following feature:
In order to save time when answering clients requests, as a webmaster,
I want to be able to manage the list of websites I am responsible for
Scenarios for this story would be:
Scenario 1: Show a list of websites
GIVEN I am an authorised administrator
AND I am managing several websites
THEN I should see a list of all the sites I manage
Scenario 2: Add website to list
GIVEN I am an authorised administrator
WHEN I enter all the required information for a new site and save it
THEN I should see that site in my own sites list
Scenario 3: Edit website from list
GIVEN I am an authorised administrator
WHEN I edit the site informations
THEN I the changes should be visible in my sites list
...
Now what if you want to go into data validation stuff like "site should have a title" for instance. To me there are two different ways to approach this. You can test that from the user's perspective with a full-stack test or test that there is some validation at the object level.
Let's assume the following scenario:
Scenario: New site has no title
GIVEN I'm an authorised administrator
WHEN I forget to fill in the title for a new site and save it
THEN I should be warned the site is not valid
You can use cucumber or specflow to run this scenario from the UX, therefore using some kind of browse-based proxy to test your app. That is usually slow as it hits the whole system and simulates a real user. It's an option, but I don't think it's the best though. IMO not all tests should be run against the UX and having too many Gherkin features can be a pain to maintain, that's why I prefer focusing on having the happy or critical path (usually I ask myself, where does the money comes from) tested full-stack and put the rest at lower levels.
You can still use Gherkin for these unit tests if you'd like. But that is not mandatory. You only need a way to show your customer you actually have a test for all those specific format controls and validation checks.
That doesn't mean you are not doing BDD anymore, you can still use the given-when-then-should pattern in rspec if you're a rubyist, or any other testing framework you use.
Hope that clarifies all this, let me know if there are any confusing parts...
I think Marc simply deserves the big green tick on this one, thanks to his amazingly thorough answer!
I just wanted to add a few comments.
You don't need to automate all your scenarios.
If you want to capture business requirements in a form that everyone (i.e. including non-tech savvy folks) can understand and Gherkin's Given/When/Then work for you, just go for it. There's nothing forcing you to automate all of your scenarios.
You don't need to automate all your scenarios through the UI.
Your software is made of layers that often respond to similar behaviours, via different interfaces (UI, HTTP, API, ...). Should you want to describe fine-grained business rules (i.e. site name constraints) with automated gherkin scenarios, you could write step definitions that talk directly to your domain layer instead of going through the user interface. That would probably still give you a decent level of confidence.
As a side note, I would recommend not to use Given/When/Then in classic testing frameworks (i.e. those that only devs can see!) if your purpose is to share your tests/requirements with non-tech people.
Have conversations!
Above all, BDD is about better communication: try to talk more, involve your developers (or some of them) earlier in the process so that they gain more knowledge, sooner. Formalising Gherkin scenarios comes in a second phase. Automating them should even be further down your priority list!

What are the permissions required in desire2learn (D2L) Valence PUT call for .../courses?

I continue to get a "HTTP/1.1 403 Forbidden" response from a PUT request to /d2l/api/lp/1.2/courses/7917 . This may be a permission problem with the user/role that I'm using, but I can't figure out what specific permissions may be required. Can anyone point me to a list or matrix of valence routes and required permissions? Or, answer for this specific one?
The same appid/userid/username works for the GETs associated with the same path.
confused...
cwt
The permissions associated with API calls should mirror the permissions you'd have to have if you were to perform the relevant function through the Learning Envrionment's web UI. You can think about this problem in two ways:
Frame the question in terms of a user role: identify the class of users you'd reserve this ability for in your existing configuration, and ensure that a user of that role can make the call through the API as you'd expect.
Frame the question in terms of an abstract single user: start with a role that has no privileges and add permissions until you arrive at only the ones required for the API call. This is not a trivial exercise, and the first way is far more useful in the long run.
In this particular case, because the API requires you provide a complete course offering set of properties when you want to update it, you have to have permission to alter all the properties in the set (under the Manage Courses tool). You also need to be able to see the course info in the first place, so you need to have Course Management Console > See Course Info as well.
You're probably safest to look at the permissions array in the Manage Courses and Course Management Console tools for the user roles that would do this thing in the web UI and make sure that the users employing your app also have a similar permissions array specified in those tools.

Access Transactions in Quickbooks Online

I'm using trying to interface with Quickbooks Online for an internal application that will push and pull transactions using qbXML. My problem is that I can't figure out which message I need to send in order to list and add the items listed under the "Banking" > "Registers" page. I've gone through the messages listed in the Onscreen Reference for Intuit Software Development Kits and none of them seem to give me this information.
Also, does anyone know of a list that explains what each message does?
If you're in a bank account register, you're writing checks. There are 3 kinds of checks in QuickBooks:
Expense checks - if you added a check directly in the register window, you would be adding an expense check.
Bill payment checks - these appear in a check register, but you can only add them with a bill payment operation.
Payroll checks - these appear in the check register, but they can only be added using the Intuit Payroll Service or by enabling manual payroll (almost no one does manual payroll in actual practice, but it is good to know about for testing purposes).
The first 2 types of checks have their own message type: the Add/Mod Check and Add/Mod BillPayment messages respectively. Payroll checks can't be added by the SDK. You can query all 3 types using a Transaction query message. I should also mention that it's possible to add an entry in any register using a journal entry, but that's not a good idea unless you are certain you know what you're doing.
I hate to tell you this, but the best reference for QuickBooks messages is the one you're already using. There are also XML files in the <sdk root>\docs directory that describe SDK operations. But there is really no substitute for understanding how QuickBooks operates from a user's perspective.
If you're going to be working with QuickBooks integration, it's a good idea to make friends with one or more QuickBooks Pro Advisors so you can run these kinds of issue by them. The relationship is generally mutually beneficial, since QuickBooks Pro Advisors often find it handy to have access to an SDK programmer.

D2L - User clicks on URL link, how to get User's current course

I know I can get the courses the user has, but I want to know where the user is at this moment - clicking the link to our external application. I'm building on the Getting Started example in PHP, from the valence/desire2learn.com website. We're using d2l for many of the course materials but want to produce some tracking and graphs for students to see. It would involve getting grade info (which I think I can do), having students enter hours of study (in our application), storing that information and returning a graph comparing course grade and study hours over the course. It would be much better to automatically pick the right course than to have the student pick the right course.
Can it be done (obtain which course the student's in at the time the link is clicked)? In addition to the annoyance of having to pick which course, it's possible that students are taking more than one course at a time where the teacher is using this tool.
Thanks in advance for your assistance.
If you use LTI v1.0 (Basic LTI) to build the link to launch from D2L to your external application, then the LTI context passed to your application will contain a context_id property: the value of this property will be the org unit ID that identifies the D2L organizational unit for the launch point's context (in this case, the ID of the course offering). Note that until LE v10.2.0 SP1, D2L won't send along the context_id for the top org level, but if the user launches an LTI link from a course offering context, you should get the org unit ID for the course offering.

Resources