Upgrade to Pro — share decks privately, control downloads, hide ads and more …

EuroPython 2020: ScanAPI Automated Integration Testing and Live Documentation for your API

EuroPython 2020: ScanAPI Automated Integration Testing and Live Documentation for your API


In the current IT scenario, the use of APIs is, without question, widely vast, popular, and significant. It seems at least prudent to ensure they are working properly, as expected. To guarantee the quality of the data that is being consumed or used. To ensure that communication between services is occurring as expected. To ensure the system does, in fact, what it should do.

ScanAPI is an open-source library that was created to solve all these points. ScanAPI provides an easy way to create integration tests for REST APIs via configuration files.

The three main reasons that led me to the creation of this library were:

1. To be a firefighter in a scenario where most of the reported bugs were directly related to some API contract being broken or some endpoint having a behavior different from that expected by the consumer.

2. To need to deal with APIs with outdated or mistaken documentation.

3. To need to debug an endpoint in the middle of a "chain" of other endpoints. Where I needed to recreate a state that depends on the action of other endpoints.

Given a fictitious example: debug an endpoint to reserve seats on an airplane, which depends directly on the previous call of an endpoint for user registration.

The ScanAPI is open-source and written in Python. However, it can be used in APIs created in any other programming language, since the tests provided by it are integration tests.

With ScanAPI you can:

- Use environment variables
- Create variables
- Chaining requests - making a request from a result of previous responses
- Hide sensitive information of the requests and responses in the generated report
- Write Python code - if you want, it's not necessary :)

Topics I intend to address in this talk:

- Motivation to create the library
- What problems the library solves
- How to test an API using a ScanAPI
- Show the documentation generated by ScanAPI
- An overview of how it is implemented
- Where it is currently being used
- Next steps

Project Link: https://github.com/scanapi/scanapi

- Python
- Integration tests

Type: Talk (30 mins); Python level: Intermediate; Domain level: Intermediate

Camila Maia

July 24, 2020

More Decks by Camila Maia

Other Decks in Technology


  1. Who am I? 4 - Brazilian Backend Developer - Bachelor

    of Computer Information System - Coding since 2010 - Python and Ruby - Events: Pyjamas and EuroPython
  2. Motivation Integration Errors 6 - Client sending fields different than

    what’s expected - Frontend receiving fields different than what’s expected
  3. Proposal 11 - Open Source Framework - Written in Python

    1. Provide a Live Documentation 2. Tool to implement integration tests
  4. 13

  5. 14

  6. # api.yaml api: endpoints: - name: pokeapi path: https://pokeapi.co/api/v2/ endpoints:

    - name: pokemon path: pokemon requests: - name: list_all method: get path: / How does it work? Example: PokéAPI 16
  7. 19

  8. 20

  9. 21

  10. How does it work? Integration tests ✅ 22 ... requests:

    - name: list_all method: get path: / tests: - name: status_code_is_200 assert: ${{ response.status_code == 200 }} - name: response_time_is_under_half_second assert: ${{ response.elapsed.total_seconds() < 0.5 }} https://requests.readthedocs.io - name: count_is_964 assert: ${{ response.json()["count"] == 964 }}
  11. 23

  12. How does it work? Chaining Requests ⛓ 24 - Get

    details of a Pokémon - In this case, the data is “static”, but it might not be. - https://pokeapi.co/api/v2/pokemon/bulbasaur
  13. How does it work? Chaining requests ⛓ 25 requests: -

    name: pokemon path: pokemon requests: - name: list_all method: get path: / vars: pokemon_name: ${{ response.json()["results"][0]["name"] }} tests: ... pokemon/${pokemon_name} - name: details method: get path: ${pokemon_name}
  14. 26

  15. ... scanapi: docker: - image: camilamaia/scanapi:1.0.5 steps: - checkout -

    run: name: Run ScanAPI command: | scanapi scanapi/api.yaml -c scanapi/.scanapi.yaml -o scanapi/report.html - store_artifacts: path: scanapi/report.html 29 - build-push: name: build-push-staging env: staging requires: - scanapi filters: branches: only: - master workflows: version: 2 main: jobs: - scanapi: filters: branches: only: - master
  16. How does it work? And there is more 30 -

    Language-independent - It also accepts API spec in JSON - Environment variables - Hide sensitive info in the report - Multiple files API specification - Custom templates
  17. Next Steps What about the future? 33 - Missing HTTP

    methods (current: GET, POST, PUT, PATCH, DELETE) - JSON visualization - Docs + Tutorials - Website improvements - GitHub Action And what if…. - OpenAPI
  18. Why to contribute? Join us! 34 - Backend, frontend, automation,

    design - “Pure Python” - Understand how a lib works - Test coverage > 90% - Issues with labels - i.e: good first issue
  19. Sprint Session 36 - Sprint session on this weekend -

    July 25th and 26th (free!) #sprint-scanapi More information