Supporting a talk by @jasonh_n_austin given to the @austinapi meetup on 9/25/13.. The usability of APIs has to be a forethought from product down to test. We must ensure a developer-focused mentality throughout the development lifecycle. BDD provides us with an elegant way to implement a plain English, plain text testing fixture, in a variety of languages.

1. BDD for APIs
Jason Harmon

2. Jason Harmon
• Blogger on apiux.com
• API Architect @uShip
• Likes Python
• Works in everything else
• Funny mustache
• Loves weiner dogs

5. Agile
• INDIVIDUALS AND INTERACTIONS
over processes and tools
–Inside our organization and with our
users

7. Agile
• WORKING SOFTWARE over
comprehensive documentation
–Not only in our product but our
testing & regression

9. Agile
• RESPONDING TO CHANGE over
following a plan
– APIs will change for your
business, better have tests

11. Agile
• CUSTOMER COLLABORATION
over contract negotiation
– Get good at sharing ideas

12. What is BDD?
• “Behavior Driven Development”
• English readable description of how our
product behaves
• Agreed upon by the team: not Dev, QA or
product owned
• Used to verify the acceptance criteria for
features in a product
• Conceptually like TDD (test-first), but for
functional testing (not code architecture)

13. * Agile Testing: A Practical Guide for Testers and Agile Teams (Addison-Wesley, 2009)
http://lisacrispin.com/2011/11/08/using-the-agile-testing-quadrants/

14. Q2 Automated & Manual Tests
Functional Tests
Examples
Story Tests
Prototypes
Simulations
SupportingtheTeam
Business Facing

15. Polyglot friendly
• Cucumber
– Ruby-based, the granddaddy of BDD
• Cucumber-JVM
– Java implementation, plays nice with Junit and all JVM
languages (Groovy is quite nice here)
• Specflow
– .NET, Visual Studio integrated
• Lettuce
– Python-based, very similar to Cucumber
• Behat
– PHP-based

16. Gherkin
One Description to Rule Them All
• https://github.com/cucumber/gherkin
• Business Readable
• DSL
• Not code

18. Gherkin Example
Imperative Style
Scenario: Get nearby place name
Given I use the geonames host
When I access the resource url "/findNearbyPlaceNameJSON"
And I provide parameter "username" as "jharmon"
And I provide parameter "lat" as "30.4754724"
And I provide parameter "lng" as "-98.1564068"
And I retrieve the JSON results
Then the status code should be 200
And it should have a list "geonames"
And the list should have at least 1 item

19. Gherkin Example
Declarative Style
Scenario: Get nearby place name
Given I use the geonames host
When I use the “Find Nearby Place by JSON” endpoint
And I identify my “geonames” user credentials
And I provide coordinates 30.4754724, -98.1564068
And I retrieve the JSON results
Then it should have at least 1 valid "geonames" item

20. Behavior Driven
• User experience trumps all
• API is no exception
• Treat API consumers like first class citizens
• Describe how your API behaves from a
consumer perspective

22. Step Definitions

23. Scenarios
“…until it’s green like a cuke”

24. Scenario outlines

25. Errors
Red means stop

26. Tags
Lots of power to selectively run groups of tests

32. Agreement
• Decide during planning how you will test for
Acceptance Criteria
• …AS A TEAM…
• Gherkin/feature definitions will allow a
ubiquitous language
• Technically, this can get easier as the critical
mass of your API interactions is in your testing
framework, and scenario steps are predictable

33. Productivity
• Stakeholders know what they’re getting
• Devs know how to build it
• Testers know how to test it
• Product knows how to sign off
• Documentation has a head start

36. Domain Language
• Focus on how you describe everything
• Find agreement on how to describe behavior
• Recognize when behavior is different than
before
– “Wait, we’ve never deleted before!”
• Homework: Domain Driven Design

38. Share!
• All BDD tests can be committed to
SCM, including branches
• Provide process which allows collaborative
coding on building test framework
• Devs provide expertise on building a scalable
test framework
• Testers utilize existing step definitions to
quickly build out tests

39. Continuous Integration
• Regression is running all the time
• Use tags to select the right depth of regression
• Very fast identification of what’s broken

41. Samples
• Python/Lettuce
– https://github.com/jasonh-n-austin/api-bdd-tests
• Groovy/Cucumber-JVM
– https://github.com/jasonh-n-austin/TwitterRestTests
• .NET/SpecFlow
– https://github.com/jasonh-n-austin/TwitterRestTests

42. Thank You
Jason Harmon
@jasonh_n_austin
http://jhr.mn