Tech Talk @ Red Hat

Transcript

1. @cmaiacd
   ScanAPI
   Automated Integration Testing and Live Documentation for your API
   Tech Talk @ Red Hat - October 2020
   Camila Maia
   

   View Slide

2. @cmaiacd
   You find this presentation at:
   speakerdeck.com/cmaiacd
   

   View Slide

3. @cmaiacd
   Motivation
   
   Everything started in a week which I as Firefighter
   

   View Slide

4. @cmaiacd
   I work at...
   

   View Slide

5. @cmaiacd
   Who am I?
   - Brazilian Backend Developer
   - Bachelor of Computer Information System
   - Coding since 2010
   - Python and Ruby
   - Events: Pyjamas, EuroPython, Python Brasil...
   

   View Slide

6. @cmaiacd
   Motivation
   
   Everything started in a week which I as Firefighter
   

   View Slide

7. @cmaiacd
   Motivation
   Integration Errors
   - Client sending fields different
   than what’s expected
   - Frontend receiving fields
   different than what’s
   expected
   

   View Slide

8. @cmaiacd
   Motivation
   - Missing endpoints
   - Missing fields
   - Misinformation
   Outdated documentation
   

   View Slide

9. @cmaiacd
   Motivation
   /reserve/:seat_id
   flight_id? airplane_id?
   passenger_id?
   Is the airplane available?
   ????
   Hard to recreate scenarios
   

   View Slide

10. @cmaiacd
    Motivation
    Hard to recreate scenarios
    

    View Slide

11. @cmaiacd
    

    View Slide

12. @cmaiacd
    Proposal
    - Open Source Framework
    - Command Line Interface (CLI)
    - Written in Python
    1. Provide a Live Documentation
    2. Tool to implement Integration Tests
    

    View Slide

13. @cmaiacd
    PokéAPI: https://pokeapi.co
    $ http https://pokeapi.co/api/v2/pokemon/
    How does it work?
    Example: PokéAPI
    

    View Slide

14. @cmaiacd
    

    View Slide

15. @cmaiacd
    

    View Slide

16. @cmaiacd
    How does it work?
    Installing: $ pip install scanapi
    Example: 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: /
    How does it work?
    Example: PokéAPI
    path: https://pokeapi.co/api/v2/ pokemon /
    name: pokeapi :: pokemon :: list_all
    

    View Slide

18. @cmaiacd
    How does it work?
    Running
    Example: PokéAPI
    

    View Slide

19. @cmaiacd
    How does it work?
    Documentation
    

    View Slide

20. @cmaiacd
    

    View Slide

21. @cmaiacd
    

    View Slide

22. @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 }}
    How does it work?
    https://requests.readthedocs.io
    Integration tests ✅
    

    View Slide

23. @cmaiacd
    

    View Slide

24. @cmaiacd
    How does it work?
    Chaining Requests ⛓
    - 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
    

    View Slide

25. @cmaiacd
    How does it work?
    ...
    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

26. @cmaiacd
    

    View Slide

27. @cmaiacd
    How does it work?
    And there is more
    - Language-independent
    - It also accepts API spec in JSON
    - Environment variables
    - Hide sensitive info in the report
    - Multiple files API specification
    - Delay between requests
    - Custom templates
    - VS Code Plugin
    

    View Slide

28. @cmaiacd
    Adding
    ScanAPI to
    your project - CIs
    - GitHub Action
    

    View Slide

29. @cmaiacd
    Adding ScanAPI to a project
    

    View Slide

30. @cmaiacd
    Adding ScanAPI to a project
    Example: CircleCI
    

    View Slide

31. @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

32. @cmaiacd
    Adding ScanAPI to a project
    Example: GitHub Action
    

    View Slide

33. @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

34. @cmaiacd
    scanapi.dev
    

    View Slide

35. @cmaiacd
    Next Steps
    What about the future?
    - Missing HTTP methods (current: GET, POST, PUT, PATCH, DELETE)
    - Improve Documentation
    - Create a Tutorial
    - Improve Contributing Documentation
    And what if we could….
    - Export to: OpenAPI, Postman Collection, Insomnia…
    - Call python modules
    

    View Slide

36. @cmaiacd
    - GitHub Issues (per project)
    - Dashboards. Ex: Hacktoberfest
    - Spectrum (events, sprints...)
    Communication
    Let’s get in touch!
    

    View Slide

37. @cmaiacd
    github.com/scanapi ⭐
    

    View Slide

38. @cmaiacd
    THANK YOU!
    @cmaiacd camilamaia
    ‍
    cmaiacd.com
    

    View Slide