Given this API:
{{base_url}}/json/1F/flightavailability/adults=1&departureairport=CRL&departuredate=20190509&destinationairport=CZL
All the parameters are mandatory except "adults". I need to write a BDD scenario and step definition for them to automate the scenario : response should be "422, unprocessed" if any of these mandatory parameters are missing.
I always like to have a conversation when I'm looking at BDD scenarios, even if it's for an API rather than a UI. I imagine the conversation going a bit like this:
Shobha: So you don't need to know how many adults are travelling to
process this, but you do need departure airport, departure date and
destination airport?
Business: That's right. If we don't know how many adults are
travelling, we assume it's 1, and we give back the available flights,
priced with 1 ticket. Otherwise, we show all available flights and
prices for the number of adults travelling.
Tester: What if there are no flights on that date?
Business: Ah, then it should say there are no flights.
Tester: What if there's 2 adults travelling, but only 1 seat on the
plane?
Business: Oh, good catch - well, we should filter that out too.
Shobha: OK, so that's 5 scenarios - the one where mandatory data is
missing, the one with no flights,
the one where the flight with too few seats is filtered out,
the one with 1 adult by default, and the one with 2 adults.
(I put the tester in there because they're really good at spotting the scenarios that nobody else thinks of.)
So, having had the conversation about what the system should do, we now have some different scenarios.
The context in which the scenario takes place - everything that was created before-hand - is the "Given". The action that takes place (submitting a search for flights) is the "When". The outcomes that result are the "Thens". You can include the set-up of the URL in the "Given" - try to make it phrased in the language of the business if you can, rather than the language of the API.
I also like to make things concrete (provide examples of destinations, departure dates and airports), because it helps us to think about other scenarios.
So for the "mandatory data missing" scenario, I would have something like:
Given a search for a flight on 17 Sep 2028 from LHR
When the search is submitted
Then the submitter should be told that the request could not be processed
And the text should contain "missing destination airport"
I wouldn't create end-to-end scenarios for every missing field; it's enough to have one at the system level. Put the rest in unit tests (see Testing Pyramid; avoid the Testing Ice Cream Cone). When you've written them, get feedback on them to see if you understood correctly.
Your post is missing information about what happens in the event of a successful submission; I have made many assumptions here! I would probably group the successful submissions with the unsuccessful submissions, unless there are too many and it gets confusing, then split them up.
Of course, you might just be testing validation / anti-corruption layers! But if you're doing that, just do it in unit tests - you don't need BDD tools.
Related
I'd love to develop my custom software to monitor my monthly expenses, but I'm struggling on the first step. Rather than having to input any expense into a big spreadsheet every now and then, I'd like to parse my banking credit card statement, to get as much information as possible.
From the most important to the least, here's what I'd like to know about each expense: price, category (food / travel / home...), date, store name, location.
However I don't know how to guess the category / shop corresponding to a given statement. If understand correctly, there is no real convention for the text, though most often it's the name of the owning company, which might not be the name of the store.
05/06 CB SAPPORO 10 -> 10$, Restaurant, 05/06, _name_of_the_restaurant_
Tbh I'm surprised that I could find anything online, it seems like something many people might want to do. Is there any kind of standard database, or existing library to do that ? How do the services which do that do it ?
Any help / redirection would be greatly appreciated :)
If two scenarios can occur at the same time, does that (always/ever) constitute a third scenario?
My current thinking is that they are not necessarily exclusive (depends on the scenario). If you have two scenarios that could occur at the same time that they would only require a third scenario if the Given/When/Then steps do not merge implicitly or if one scenario takes precedence over the other.
This question has arisen whilst thinking about scenarios for what is essentially a form of injection in which Collections of objects get injected into another object ( https://github.com/jameskennard/mockito-collections ). So given the two scenarios "Class of object under test has a List of collaborators" and "Class of object under test has a Set of collaborators". Both could occur at the same time so a third scenario could be "Class of object under test has a List and a Set of collaborators". But it doesn't feel right, it's just too verbose, I think the Given/When/Then steps would be seen to merge implicitly. (Have a bad feeling I may have just answered my own question)
Anyone have any differing thoughts?
I think the key here is the behavior. The potential third scenario ("Class of object under test has a List and a Set of collaborators") that you're asking about is of course real but the behavior is already covered by the other two scenarios so I'd say there is no need to write another scenario.
If the combination of givens was to result in different behavior there would certainly be a third scenario but I believe the two you have cover the behavior you're looking to define.
At the moment, your sentences above are describing state rather than behavior.
What is the different outcome you get in each of the different contexts? I would expect something like this:
Given my CUT has five collaborators
When I do my thing with the class
Then it should use each collaborator in turn.
Given my CUT has five collaborators
And the fourth and fifth collaborators are identical
When I do my thing with the class
Then it should only use the fourth collaborator once.
That would illustrate the different behavior of the list (ordered) and the set (no duplicates).
If those two elements are truly beneficial independently, then yes, they're two separate scenarios. If they both have to be present for the class to have any value, I'd merge them into one:
Given my CUT has five collaborators
And the fourth and fifth collaborators are identical
When I do my thing with the class
Then it should use each collaborator in turn
And it should only use the fourth collaborator once.
An example of two simultaneous benefits might be getting cash out of an ATM, in which the cash is delivered and the account is also debited. You couldn't do either of those independently. Offering a receipt for the transaction would be a separate benefit, as it doesn't need to occur for an ATM to be of value. Hope this helps to make the distinction.
We all love REST, especially when it comes to the development of APIs. Doing so for the last years I always stumble upon the same problem: nested resources. It seems we're living at the two edges of a scale. Let me introduce an example.
/galaxies/8/solarsystems/5/planets/1/continents/4/countries.json
Neato. Cases like that seem to happen everywhere, no matter in what shape they materialize. Now I'd like to being able to fetch all the countries in a solar system while being able to fetch countries deeply scoped as shown above.
It seems I have two choices here. The first one, I flatten my nested structure and introduce a lot of GET parameters (that need to be well documented and understood by my API user) like so:
/countries.json?galaxy=8&solarsystem=5&planet=1&continent=4
I could flatten all my resources like so and won a unique endpoint base URL for each one. Good point … unique endpoints per resource!
But what's the price? Something that does not feel natural, is not discoverable and does not behave like the tree structure below my resources. Conclusion: Bad idea, but well practiced.
On the other hand I could try to get rid of as many additional GET parameters as possible, creating endpoints like that:
/galaxies/8/solarsystems/5/countries.json
But I also needed:
/galaxies/8/solarsystems/5/planets/1/continents/4/countries.json
This seems to be the other side of the scale. Least number of additional GET parameters, more natural behave but still not what I expected as an API user.
The most APIs I worked with in the last year follow the one or the other paradigm. It seems there is at least one bullet to bite. So why not doing the following:
If there are resources that nest naturally, lets nest them exactly in the way we'd expect them to be nested. What we achive is at first a unique endpoint for every resource when we stay like that:
/galaxies.json
/galaxies/8/solarsystems.json
/galaxies/8/solarsystems/5/planets.json
/galaxies/8/solarsystems/5/planets/1/continents.json
/galaxies/8/solarsystems/5/planets/1/continents/4/countries.json
Ok, but how to solve the initial problem, I wanted to fetch all the countries in a solar system while still being able to fetch countries fully scoped under galaxies, solar systems, planets and continents? Here's what feels natural for me:
/galaxies/8/solarsystems/5/planets/0/continents/0/countries.json # give me all countries in the solarsystem 5
/galaxies/8/solarsystems/0/planets/0/continents/0/countries.json # give me all countries in the galaxy 8
… and so on, and so on. Now you may argue "ok, but the zero there ….." and you are right. Does not look really nice. So why not change the two upper calls to something like that:
/galaxies/8/solarsystems/5/planets/all/continents/all/countries.json # give me all countries in the solarsystem 5
/galaxies/8/solarsystems/all/planets/all/continents/all/countries.json # give me all countries in the galaxy 8
Neat eh? So what do we achive? No additional GET parameters and still stable base URLs for each resources endpoint. What's the price? Yep, at least longer URLs especially during testing by hand using tools like curl.
I wonder wether this could be a way to improve not only the maintainability but also the ease of use of APIs. If so, why does not anyone take an approach like that. I can not imagine to be the first one having that idea. So there must be valid counter arguments against an approach like that. I don't see any. Do you?
I would really like to hear your opinion and arguments for or against an approach like that. Maybe there are ideas for improvement … would be great to hear from you. In my opinion this could lead to much better structured APIs, so hopefully someone will read that and reply.
Regards.
Jan
It would all depend on upon how the data is presented. Would the user really need to the know the galaxy # to find a specific country? If so them what you propose makes sense. However, it seems to me that what you are proposing, while structured and presented well, doesn't allow for clients to search for child element unless the parent is a known quantity.
In your example, if I had a specific id for a continent I would need to know the planet, solar system and galaxy as well. In order to find the specific continent I would need to get all for each possible parent until I found the continent.
Presenting structured data in this manner if fine. Using this structure when you only have a piece of the data may be a bit cumbersome. It all depends upon what you are trying to accomplish.
Nested resource URLs are usually bad. The approach I generally take is to use unique IDs.
Design your DB so that it is only going to have one continent with ID 4. Then, instead of the horrible /galaxies/8/solarsystems/5/planets/1/continents/4/countries.json, all you need is the simple /continents/4/countries.json. Clear, sufficient, and memorable.
The :shallow routing option in Rails does this automatically.
For "all countries in a solar system", I'd use /solar_systems/5/countries.json -- that is, don't try to shoehorn it into the generic URL scheme. (And note the underscore.)
I have the strange aversion to passing in multiple ID parameters to a single stored procedure. For example, this feels just wrong:
GetMyObject(ListofIDs, OtherParam1, OtherParam2, ...)
I understand HOW to do it (correctly if I must).. but I don't feel like I should do it. I feel like it defeats the purpose of a "get item" stored procedure/sub routine. I feel like I should build my SPs to support appropriate filter parameters. If my caller has a list of IDs, shouldn't they call the sp that many times?
Help?
A "get item by ID" routine should never return more than one object, because that makes absolutely no linguistic sense.
A "get items by IDs" routine? Sure, if you have a decent use-case for it and it'll be used often enough.
But most of the time, yes, instead of a routine returning multiple items by ID, you want a routine that returns items based on application-appropriate filtering parameters (e.g. "give me all transactions from January 8th for more than $10").
By the way, sometimes a range of IDs (e.g. everything between 5 and 10) is a perfectly valid set of filters!
Incidentally, this isn't necessarily just a MySQL or SQL-in-general issue. Almost any sort of dataset querying API in any language will present these same design questions, and their answers will usually be highly similar.
Imagine you had a group of product categories organized in a nice tree hierarchy and you wanted to provide hackable urls to browse these. You could do something like this
/catalog/categorya/categoryb/categoryc
You could then quite easily figure out which category you should list the products for (note that the full URL is needed since you could have categories with the same name but at different locations in the hierarchy)
Now what would be a good approach to add product information in that as well? To give you an example, you wanted to display the product Oblivion for this category
/catalog/games/consoles/playstation/adventure
It's tempting to just add the product at the end of the url
/catalog/games/consoles/playstation/adventure/oblivion
but the moment you do so you loose the ability to know if its category or a product which is called oblivion. I personally feel that not being forced to add a suffix such as .html
/catalog/games/consoles/playstation/adventure/oblivion.html
would be the nicest solution and using some sort of prefix, such as
/catalog/games/consoles/playstation/adventure/product:oblivion
You could also add some sort of trigger like
/catalog/games/consoles/playstation/adventure/PRODUCT/oblivion
not as nice either and you would (even though its very unlikely it would be a problem) restrict yourself from having a category called product
So far a suffix solution looks like the most user-friendly approach that I can think of from the top of my head but I'm not fond of having to use an extension
What are your thoughts on this?
Deep paths irk me. They're hideous to share.
/product/1234/oblivion --> direct page
/product/oblivion --> /product/1234/oblivion if oblivion is a unique product,
--> ~ Diambiguation page if oblivion is not a unqiue product.
/product/1234/notoblivion -> /product/1234/oblivion
/categories/79/adventure --> playstation adventure games
/categories/75/games --> console games page
/categories/76/games --> playstation games page
/categories/games --> Disambiguation Page.
Otherwise, the long urls, while seeming hackable, require you to get all node elements right to hack it.
Take php.net
php.net/str_replace --> goes to
http://nz2.php.net/manual/en/function.str-replace.php
And this model is so hackable people use it all the time blindly.
Note: The .html suffix is regarded by the W3C as functionally meaningless and redundant, and should be avoided in URLs.
http://www.w3.org/Provider/Style/URI
Lets disect your URL in order to be more DRY (non-repetitive). Here is what you are starting with:
/catalog/games/consoles/playstation/adventure/oblivion
Really, the category adventure is redundant as the game can belong to multiple genres.
/catalog/games/consoles/playstation/oblivion
The next thing that strikes me is that consoles is also not needed. It probably isn't a good idea to differentiate between PC's and Console machines as a subsection. They are all types of machines and by doing this you are just adding another level of complexity.
/catalog/games/playstation/oblivion
Now you are at the point of making some decisions about your site. I would recommend removing the playstation category on your page, as a game can exist across multiple platforms and also the games category. Your url should look like:
/catalog/oblivion
So how do you get a list of all the action games for the Playstation?
/catalog/tags/playstation+adventure
or perhaps
/catalog/tags/adventure/playstation
The order doesn't really matter. You have to also make sure that tags is a reserved name for a product.
Lastly, I am assuming that you cannot remove the root /catalog due to conflicts. However, if your site is tiny and doesn't have many other sections then reduce everything to the root level:
/oblivion
/tags/playstation/adventure
Oh and if oblivion isn't a unique product just construct a slug which includes it's ID:
/1234-oblivion
Those all look fine (except for the one with the colon).
The key is what to do when they guess wrong -- don't send them to a 404 -- instead, take the words you don't know and send them to your search page results for that word -- even better if you can spell check there.
If you see the different pieces as targets then the product itself is just another target.
All targets should be accessable by target.html or only target.
catalog/games/consoles/playstation.html
catalog/games/consoles/playstation
catalog/games/consoles/playstation/adventure.html
catalog/games/consoles/playstation/adventure
catalog/games/consoles/playstation/adventure/oblivion.html
catalog/games/consoles/playstation/adventure/oblivion
And so on to make it consistent.
My 5 cents...
One problem is that your user's notion of a "group of product categories organized in a nice tree hierarchy" may match yours.
Here's a google tech talk by David Weinberger's "Everything is Miscellaneous" with some interesting ideas on categorizing stuff:
http://www.youtube.com/watch?v=x3wOhXsjPYM
#Lou Franco yeah either method needs a sturdy fallback mechanism and sending it to some sort of suggestion page or seach engine would be good candidates
#Stefan the problem with treating both as targets are how to distinguish them (like I described). At worst case scenario is that you first hit your database to see if there is a category which satisfies the path and if it doesn't then you check if there is a product which does. The problem is that for each product path you will end up making a useless call to the database to make sure its not a category.
#some yeah a delimiter could be a possible solution but then a .html suffix is more userfriendly and commonly known of.
i like /videogames/consolename/genre/title" and use the amount of /'s to distinguish between category or product. The only thing i would be worried about multi (or hard to distinguish) genre. I highly recommend no extension on title. You could also do something like videogames(.php)?c=x360;t=oblivion; and just guess the missing information however i like the / method as it looks more neat. Why are you adding genre? it may be easier to use the first letter of the title or just to do videogame/console/title/
My humble experience, although not related to selling games, tells me:
editors often don't use the best names for these "slugs", they don't chose them wisely.
many items belong (logically) to several categories, so why restrict them (technically) to a single category?
Better design item urls by ids, (i.e. /item/435/ )
ids are stable (generated by the db, not editable by the editor), so the url stands a much bigger chance at not being changed over time
they don't expose (or depend on) the organization of the objects in the database like the category/item_name style of urls does. What if you change the underlying design (object structure) to allow an item to belong to multiple categories? the category/item urls suddenly won't make sense anymore; you'll change your url design and old urls might not work anymore.
Labels are better than categories. That is to say, allowing an item to belong to several categories is a better approach than assigning one category to each item.
the problem with treating both as
targets are how to distinguish them
(like I described). At worst case
scenario is that you first hit your
database to see if there is a category
which satisfies the path and if it
doesn't then you check if there is a
product which does. The problem is
that for each product path you will
end up making a useless call to the
database to make sure its not a
category.
So what? There's no real need to make a hard distinction between products and categories, least of all in the URI, except maybe a performance concern over an extra database call. If that's really such a big deal to you, consider these two suggestions:
Most page views will presumably be on products, not categories. So doing the check for a product first will minimize the frequency with which you need to double up on the database lookups.
Add code to your app to display the time taken to generate each page, then go out to the nearest internet cafe (not your internal LAN!) with a stopwatch. Bring up some pages from your site and time how long each takes to come up. Subtract the time taken to generate the page. Also compare the time taken to generate one-database-lookup pages vs. two-database-lookup pages. Then ask yourself, when it takes maybe 1-2 seconds total to establish a network connection, generate the content, and download the content, does it really matter whether you're spending an extra 0.05 second or less for an additional database lookup or not?
Optimize where it matters, like making URLs that will be human-friendly (as in Chris Lloyd's answer). Don't waste your time trying to shave off the last possible fraction of a percent.