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

https://ep2020.europython.eu/talks/CjFe7r4-scanapi/

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

Prerequisites:
- Python
- REST APIs
- Integration tests

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

Transcript

1. ScanAPI Automated Integration Testing and Live Documentation for your API Camila Maia 1 EuroPython 2020
2. Motivation Everything started in a week which I as Firefighter 2
3. I work at... 3
4. Who am I? 4 - Brazilian Backend Developer - Bachelor of Computer Information System - Coding since 2010 - Python and Ruby - Events: Pyjamas and EuroPython
5. Motivation Everything started in a week which I as Firefighter 5
6. Motivation Integration Errors 6 - Client sending fields different than what’s expected - Frontend receiving fields different than what’s expected
7. Motivation Outdated documentation 7 - Missing endpoints - Missing fields - Misinformation
8. Motivation Hard to recreate scenarios 8 /reserve/:seat_id flight_id? airplane_id? passenger_id? Is the airplane available? ????
9. Motivation Hard to recreate scenarios 9
11. Proposal 11 - Open Source Framework - Written in Python 1. Provide a Live Documentation 2. Tool to implement integration tests
12. PokéAPI: https://pokeapi.co $ http https://pokeapi.co/api/v2/pokemon/ How does it work? Example: PokéAPI 12
15. How does it work? Example: PokéAPI 15 Installing: $ pip install scanapi
16. # 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
17. How does it work? Example: PokéAPI 17 Running
18. How does it work? Documentation 18
22. 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 }}
24. 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
25. 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}
27. Adding ScanAPI to a project 27
28. Adding ScanAPI to a project 28
29. ... 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
30. 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
31. Can I start using it? For sure! 31
32. scanapi.dev 32
33. 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
34. 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
35. Why to contribute? Join us! 35 How Open Source Changed My Life with Max Stoiber
36. Sprint Session 36 - Sprint session on this weekend - July 25th and 26th (free!) #sprint-scanapi More information
37. github.com/scanapi ⭐ 37
38. We are hiring! Loadsmart 38 Direct Link
39. THANK YOU @cmaiacd camilamaia #talk-scanapi #sprint-scanapi