Streamlined Geek Talk
Download as PPT, PDF0 likes522 views
The document discusses a streamlined approach to API documentation and testing using Rails and Cucumber, aimed at improving communication among developers and ensuring interface stability. It covers workflows involving continuous integration, pre-existing codebases, and the generation of HTTP traffic logs, as well as employing various tools like Cucumber and WeBrat. The authors emphasize the importance of keeping documentation up-to-date through automated testing and continuous integration practices.
Streamlined Geek Talk
- 1. Streamlined Geek Talk Web Services APIs and Always Up-to-Date Documentation with Rails and Cucumber by Sarah Allen and Wolfram Arnold
- 2. multiple clients, multiple developers
- 3. Use cases • Corporate teams – communication between developers – outsourced development – documenting an open API • Open source – documenting API – interface stability
- 4. Always up-to-date Documentation spec = test = doc
- 5. Target Workflow New Client App Legacy Code Feature Docs Server Engineer Covered? writes scenario Client Engineer Server Engineer CI Pass? writes code writes code
- 6. How we made it happen • Pre-existing codebase • Generate HTTP traffic logs from client apps • Wrote cucumber features for each use case
- 7. Tools • Cucumber BDD framework – http://cukes.info/ – http://wiki.github.com/aslakhellesoy/cucumber • Webrat (gem) • Using DB fixtures in cucumber – http://wiki.github.com/aslakhellesoy/cucumber/fixtures • Using XML fixtures to compare server response – xmlsubsetmatcher library • Continuous integration – hudson, cruisecontrol.rb, integrity • Example: – http://github.com/mightyverse/cucumber_xml
- 8. Rails Web Services app/controllers/projects_controller.rb r e s p o n d _ t o d o |f o r m a t | f o r m a t .h t m l # v ie w s / p r o je c t s / in d e x . h t m l . e r b f o r m a t .x m l # v ie w s / p r o je c t s / in d e x . x m l . b u ild e r e nd
- 9. Rails Web Services app/views/projects/index.xml.builder x m l . in s t r u c t ! x m l . p r o je c t s d o x m l . t o t a l @p r o je c t s . le n g t h @p r o je c t s . e a c h d o |p r o je c t | x m l . p r o je c t d o x m l . n a m e p r o je c t . n a m e x m l . n o t e s p r o je c t . n o t e s e nd e nd e nd
- 10. Feature Scenarios Feature: Project XML API In order to read project data data As a device or client application using the XML REST interface I want to make GET requests to the /projects URL Scenario: Get Medium When I send an XML GET to /projects.xml Then I get a 200 (success) status result And the response header Content-Type matches application/xml And the response should be a superset of the file: "xml/projects.xml"
- 11. Workflow • Publish doc from source repository • Continuous integration run feature scenarios on every checkin • All engineers have access to CI • Separate test and production environments
- 12. Results Surfaces undocumented requirements Highlights use of undocumented API’s Software works well
- 13. Always up-to-date Documentation spec = test = doc Wolfram Arnold Sarah Allen rubyfocus.biz ultrasaurus.com www.mightyverse.com