57º Python Floripa on-line: Como testar e documentar REST APIs com ScanAPI

57º Python Floripa on-line:
https://www.meetup.com/Floripa-Python-Meetup/events/276866977/

Sobre a ScanAPI:

A ScanAPI é um framework de código aberto escrita em Python que possibilita a criação de testes de integração para REST APIs.

Através de um arquivo de configuração (YAML/JSON), você consegue implementar testes automatizados para os endpoints da sua API. O framework gera um relatório de execução dos testes que também pode ser utilizado como a própria documentação da API

Essa palestra visa mostrar um pouco do funcionamento da ScanAPI, como ela pode ajudar o seu time na sua arquitetura de micro serviços e discutir os próximos passos a serem seguidos

Website do projeto: https://scanapi.dev

Transcript

1. @cmaiacd
   ScanAPI
   Como testar e documentar REST APIs com ScanAPI
   57º Python Floripa on-line - Mar 2021
   Camila Maia
   

   View Slide

2. @cmaiacd
   Esta apresentação está disponível em:
   speakerdeck.com/cmaiacd
   

   View Slide

3. @cmaiacd
   Motivação
   🚒
   Tudo começou numa bela semana de firefighter… 🔥
   

   View Slide

4. @cmaiacd
   Eu trabalho na...
   

   View Slide

5. @cmaiacd
   Quem sou eu?
   - Desenvolvedora Backend
   - Formada em Sistemas de Informação pela UFSC
   - Entrei na área em 2010
   - Python and Ruby
   - Organização de eventos:
   Pyjamas, EuroPython, Python Brasil….
   

   View Slide

6. @cmaiacd
   Motivação
   🚒
   Tudo começou numa bela semana de firefighter… 🔥
   

   View Slide

7. @cmaiacd
   Motivação
   Erros de integração 💥
   - Clientes enviando campos
   diferentes do esperado
   - Frontend recebendo campos
   diferentes do esperado
   

   View Slide

8. @cmaiacd
   - Endpoints e campos faltantes
   - Desinformação
   Motivação
   Documentação desatualizada 📜
   

   View Slide

9. @cmaiacd
   /reservar/:id_do_assento
   id_do_voo? id_da_aeronave?
   id_do_passageiro?
   Aeronave está disponível?
   ????
   Motivação
   Dificuldade em recriar o cenário 😤
   

   View Slide

10. @cmaiacd
    Motivação
    Dificuldade em recriar o cenário 😤
    

    View Slide

11. @cmaiacd
    

    View Slide

12. @cmaiacd
    O quê a ScanAPI se propõe a fazer pela
    sua API?
    - Framework de código aberto
    - Command line interface (CLI)
    - Escrito em Python
    1. Fornecer Live Documentation
    2. Possibilitar a implementação de Testes de Integração
    

    View Slide

13. @cmaiacd
    PokéAPI: https://pokeapi.co
    $ http https://pokeapi.co/api/v2/pokemon/
    Como funciona?
    Exemplo: PokéAPI
    

    View Slide

14. @cmaiacd
    

    View Slide

15. @cmaiacd
    

    View Slide

16. @cmaiacd
    Como funciona?
    $ pip install scanapi
    Exemplo: PokéAPI
    

    View Slide

17. @cmaiacd
    # scanapi.yaml
    endpoints:
    - name: pokeapi
    path: https://pokeapi.co/api/v2/
    endpoints:
    - name: pokemon
    path: pokemon
    requests:
    - name: list_all
    method: get
    path: /
    Como funciona?
    Exemplo: PokéAPI
    path: https://pokeapi.co/api/v2/ pokemon /
    name: pokeapi :: pokemon :: list_all
    

    View Slide

18. @cmaiacd
    Como funciona?
    Executar...
    Exemplo: PokéAPI
    

    View Slide

19. @cmaiacd
    Como funciona?
    Documentação 📄
    

    View Slide

20. @cmaiacd
    

    View Slide

21. @cmaiacd
    

    View Slide

22. @cmaiacd
    

    View Slide

23. @cmaiacd
    ...
    requests:
    - name: list_all
    method: get
    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 }}
    - name: results_length_is_20
    assert: ${{ len(response.json()["results"]) == 20 }}
    - name: count_is_gte_1050
    assert: ${{ response.json()["count"] >= 1050 }}
    Como funciona?
    https://requests.readthedocs.io
    Testes de Integração ✅
    

    View Slide

24. @cmaiacd
    

    View Slide

25. @cmaiacd
    Como funciona?
    Encadeamento ⛓
    - Pegar detalhes de um Pokémon
    - Neste caso o dado é “estático”, mas poderia não ser
    https://pokeapi.co/api/v2/pokemon/bulbasaur
    

    View Slide

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

    View Slide

27. @cmaiacd
    

    View Slide

28. @cmaiacd
    Como funciona?
    E tem mais 🎉
    - Independente de linguagem!
    - Especificação da API também é aceita em JSON
    - Variável de Ambiente
    - Esconder dados sensitivos no relatório
    - Especificação da API em vários arquivos
    - Delay entre requests
    - Templates Customizados
    - VS Code Plugin
    

    View Slide

29. @cmaiacd
    ScanAPI no
    seu projeto - CIs
    - GitHub Action
    

    View Slide

30. @cmaiacd
    Adicionando ScanAPI ao seu projeto
    

    View Slide

31. @cmaiacd
    Adicionando ScanAPI ao seu projeto
    Exemplo: CircleCI
    

    View Slide

32. @cmaiacd
    Adicionando ScanAPI ao seu projeto
    Exemplo: CircleCI
    

    View Slide

33. @cmaiacd
    # my_project/.circleci/config.yml
    ...
    scanapi:
    docker:
    - image: camilamaia/scanapi:2.1.0
    steps:
    - checkout
    - run:
    name: Run ScanAPI
    command: |
    scanapi run scanapi/scanapi.yaml
    -c scanapi/scanapi.conf
    -o scanapi/report.html
    - store_artifacts:
    path: scanapi/report.html
    workflows:
    version: 2
    main:
    jobs:
    - scanapi:
    filters:
    branches:
    only:
    - master
    - build-push:
    name: build-push-staging
    env: staging
    requires:
    - scanapi
    filters:
    branches:
    only:
    - master
    

    View Slide

34. @cmaiacd
    Adicionando ScanAPI ao seu projeto
    Examplo: GitHub Action
    

    View Slide

35. @cmaiacd
    # my_project/.github/workflows/scanapi.yml
    on:
    push:
    branches: [master]
    name: Run ScanAPI
    jobs:
    scanapi:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Run automated API tests
    uses: scanapi/github-action@v1
    with:
    scanapi_version: "==2.1.0"
    arguments: "run ./pokeapi/scanapi.yaml"
    - name: Upload scanapi-report.html
    uses: actions/upload-artifact@v2
    with:
    name: ScanAPI Report
    path: scanapi-report.html
    

    View Slide

36. @cmaiacd
    scanapi.dev
    

    View Slide

37. @cmaiacd
    - GitHub
    - Issues (per project)
    - Dashboards. Ex: Hacktoberfest
    - Spectrum (events, sprints...). Future: Github Discussions
    Comunicação
    Bora trocar uma ideia! 🗣
    

    View Slide

38. @cmaiacd
    Próximos passos
    E o futuro? 🔮
    - Outros métodos HTTP (além de GET, POST, PUT, PATCH, DELETE)
    - Melhorar Documentação
    - Criar Tutoriais
    - Melhor documentação para contribuição
    E se….
    - Exportar: OpenAPI, Postman Collection, Insomnia…
    

    View Slide

39. @cmaiacd
    github.com/scanapi ⭐
    

    View Slide

40. @cmaiacd
    MUITO OBRIGADA!
    @cmaiacd camilamaia
    👩‍💻
    cmaiacd.com
    

    View Slide