Examples for API and system run jobs

[Till]

Hello!

We'd like to use BDD for the large-scale application we're just started building. The application has 3 major parts:

1. A public service REST API that will mostly used 90% internally, 10% by other consumers.
   
2. A UI that uses the API for our customers to interact with the application.
   
3. A fleet of crawlers that handle various scheduled background tasks.
   

We'll obviously use Gherkin features files for the UI. However we are unsure about the documentation of the REST API and the crawlers/tasks.

What do you recommend for API docs? Swagger/OpenAPI?

What do you recommend for the crawler, background tasks, or system documentation in general? It's by far the most crucial part of our application and has a 0% error tolerance. We'd really like to use Gherkin features file for it, but are unsure how do write stories about system processes. Could you point us to an example?

Thanks for reading!

— Till

[Tim Walker]

On Nov 10, 2016 3:16 AM, "Till" <ti...@kruss.io> wrote:
>
> Hello!
>
> We'd like to use BDD for the large-scale application we're just started building. The application has 3 major parts:
>
> A public service REST API that will mostly used 90% internally, 10% by other consumers.
> A UI that uses the API for our customers to interact with the application.
> A fleet of crawlers that handle various scheduled background tasks.
> We'll obviously use Gherkin features files for the UI. However we are unsure about the documentation of the REST API and the crawlers/tasks.
>
> What do you recommend for API docs? Swagger/OpenAPI?

Why not use Gherkin for the entirety of this?
It will be backed by tests and greatly simplifies change management and versioning.

> What do you recommend for the crawler, background tasks, or system documentation in general? It's by far the most crucial part of our application and has a 0% error tolerance. We'd really like to use Gherkin features file for it, but are unsure how do write stories about system processes. Could you point us to an example?
>
> Thanks for reading!
>
> — Till
>

> --
> Posting rules: http://cukes.info/posting-rules.html
> ---
> You received this message because you are subscribed to the Google Groups "Cukes" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to cukes+un...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Eric Kessler]

On Thursday, November 10, 2016 at 7:52:47 AM UTC-5, Halfordian Golfer wrote:

On Nov 10, 2016 3:16 AM, "Till" <ti...@kruss.io> wrote:
>
> Hello!
>
> We'd like to use BDD for the large-scale application we're just started building. The application has 3 major parts:
>
> A public service REST API that will mostly used 90% internally, 10% by other consumers.
> A UI that uses the API for our customers to interact with the application.
> A fleet of crawlers that handle various scheduled background tasks.
> We'll obviously use Gherkin features files for the UI. However we are unsure about the documentation of the REST API and the crawlers/tasks.
>
> What do you recommend for API docs? Swagger/OpenAPI?

Why not use Gherkin for the entirety of this?
It will be backed by tests and greatly simplifies change management and versioning.

> What do you recommend for the crawler, background tasks, or system documentation in general? It's by far the most crucial part of our application and has a 0% error tolerance. We'd really like to use Gherkin features file for it, but are unsure how do write stories about system processes. Could you point us to an example?
>

If you are looking to have documentation and testing all in one place, then Cucumber is a good way to go. The biggest change from project to project will be how you describe what you are documenting/testing and that depends on the domain and scope that you are trying to capture. For example, here is an example of a scenario that is abstract enough that it captures only behavior:

Scenario: Adding an item to the shopping cart

  Given a user is browsing an item

  When they indicate that they want to buy that item

  Then the item is added to their cart

The above Gherkin would be valid for either the GUI or the API and which one is being used when the the scenario is executed is up to the step definitions. You could even have two sets of step definitions so that you can run your feature set against either the GUI or the API.

That being said, most Cucumber users are more focused on documenting/testing the interface being used and if this is the case with you, then you could write two scenarios: one that uses the GUI and one that uses the API:

@gui

Scenario: Adding an item to the shopping cart

  Given a user is on an item's catalog page

  When they click on the 'Buy' button

  And they click on the shopping cart summary tab

  Then the item is displayed in the cart's item list

@api

Scenario: Adding an item to the shopping cart

  Given a request to view an item

    """

    {

      "type": "navigation_request",

      "data": { 

                   "page": "url/for/some/item.html"

                 }

    }

    """

  When an add item request is received

    """

    {

      "type": "add_to_cart",

      "data": { 

                   "item_id": "CatalogItem123456"

                 }

    }

    """

  Then a successful response is generated

    """

    {

      "type": "add_ok",

      "data": { 

                   "item_id": "CatalogItem123456"

                 }

    }

    """

Voila! You can use Gherkin to describe anything. Just pick the phrasing that works best for you.

[Till]

Thanks for your answers!

Could someone give me an example of how you'd write a test for non-user-facing features, things that only the system does in the background regularly? 

[Eric Kessler]

On Thursday, November 10, 2016 at 12:00:39 PM UTC-5, Till wrote:

Thanks for your answers!

Could someone give me an example of how you'd write a test for non-user-facing features, things that only the system does in the background regularly? 

If there's no user, then there is no one who needs to read any documentation. So, why are you documenting it? Just write some tests in your low level testing framework of choice in order to check that the system works and be on your way.

That being said, I would contend that every feature is user facing. It's just that, again, who that user is will be determined by the particular project and scope.

Take, for example, mainframe batch processing. To most of the company, it might be a mysterious black box that shuffles things around every night but, unless it has been loaded up with some artificial intelligence, it still needs telling it what to do. At the very least, something like this:

Scenario: Staging files for processing

  Given the following input files need to be processed

    | foo.dat |

    | bar.dat |

  When they are placed in "path/to/some/shared_drive"

  And batch processing occurs

  Then the following output files are generated in "path/to/somewhere_else"

    | foo.out |

    | bar.out |

And maybe that's the extent of interaction that any user has with the system. If that's the case, then you are done. No interaction means nothing to document. At a user level, that is. Please still document your source code, because some maintenance programmer in the future is going to be better at reading English than they are at reading Cobol. ;)

Eric K

[Till]

Thanks Erik, that was helpful!

[Andrew Premdas]

Personally I think you can use Cucumber productively to write API docs: but only if you don't include detail of how things are delivered.

Lets say I want to be able to get a product and its orders

Given I am an api user

When I get a product

Then I should be able to get orders from the product

With api's what you are  interested in (at least for the happy path) is the capabilities each  call gives. Once this is in place then you can think about sad paths.

When you write scenarios in this way you can ask obvious questions like

Why should I be able to get orders from the product? And this should help you write a clearer and simpler API. This is the main reason to use Cukes. If you can't ask these questions and can't change how the API behaves, i.e. if you are testing rather than driving development by defining behaviour then I wouldn't bother using Cukes

--

Posting rules: http://cukes.info/posting-rules.html
---
You received this message because you are subscribed to the Google Groups "Cukes" group.

To unsubscribe from this group and stop receiving emails from it, send an email to cukes+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

------------------------

Andrew Premdas

blog.andrew.premdas.org