Automated Integration Testing and Live Documentation for your API

Last update: Dec 30, 2022

Overview

A library for your API that provides:

Automated Integration Testing
Automated Live Documentation

Given an API specification, written in YAML/JSON format, ScanAPI hits the specified endpoints, runs the test cases, and generates a detailed report of this execution - which can also be used as the API documentation itself.

With almost no Python knowledge, the user can define endpoints to be hit, the expected behavior for each response and will receive a full real-time diagnostic report of the API!

Contents
Requirements
How to install
Basic Usage
Documentation
Examples
Contributing

Requirements

How to install

$ pip install scanapi

Basic Usage

You will need to write the API's specification and save it as a YAML or JSON file. For example:

endpoints:
  - name: scanapi-demo # The API's name of your API
    path: http://demo.scanapi.dev/api/ # The API's base url
    requests:
      - name: list_all_devs # The name of the first request
        path: devs/ # The path of the first request
        method: get # The HTTP method of the first request
        tests:
          - name: status_code_is_200 # The name of the first test for this request
            assert: ${{ response.status_code == 200 }} # The assertion

And run the scanapi command

$ scanapi run <file_path>

Then, the lib will hit the specified endpoints and generate a scanapi-report.html file with the report results.

Documentation

The full documentation is available at scanapi.dev

Examples

You can find complete examples at scanapi/examples!

This tutorial helps you to create integration tests for your REST API using ScanAPI

Contributing

Collaboration is super welcome! We prepared the Newcomers Guide to help you in the first steps. Every little bit of help counts! Feel free to create new GitHub issues and interact here.

Let's build it together 🚀

Comments

feat: add pre-commit hook to check if follow conventional commits (#438)
Description

Added a pre-commit hook to check if follow the conventional commits.

Motivation behind this PR?

QA

What type of change is this?

Check if commit message follow the conventional commits.

Checklist

[x] I have added a changelog entry / my PR does not need a new changelog entry. Instructions.

[ ] I have added/updated unit tests. Instructions.

[ ] New and existing unit tests pass locally with my changes. Instructions

[ ] I have self-documented code my changes by adding docstring(s) and comment(s). Instructions

[x] Current PR does not significantly decrease the code coverage and docstring coverage.

[x] My code follows the style guidelines of this project.

[ ] I have run ScanAPI locally and manually tested my changes. Instructions.

Issue

Closes #438
opened by hebertjulio 17
ADR 2: How to show test results in the html report
Architecture Decision Review - ADR

How are we going to show the tests in the html report

Which color should we use?

How are we going to show each test case?

How are we going to show if a test passed?

How are we going to show if a test failed?

Should we use HTTP methods with color? Yes or No?

This discussion started here

Related ADR: #164
ADR
opened by camilamaia 16
Publish Sphinx Documentation
Publish Sphinx Documentation

The #230 implemented the auto-generated code documentation using sphinx.

We can run it locally by running

$ cd documentation $ make html

And we can access it opening the file scanapi/documentation/build/html/index.html in a browser.

This is great, but it would be nice to have this documentation published somewhere else. One option would be to publish it inside our website scanapi.dev, repository: https://github.com/scanapi/website
Documentation
opened by camilamaia 13
Add anchor link for each request in the report to make it easily shareable

It would be nice to have anchor links available at each request in the report.

To share a specific request that needs review would be easier than having to scan (pun intended) through the entire report.
Feature Good First Issue Reporter Hacktoberfest

opened by loop0 11
ADR 6: How to integrate feature that converts OpenAPI file to ScanAPI file
Architecture Decision Review - ADR

We want to implement the feature of receiving a JSON OpenAPI spec and convert it into a ScanAPI spec file.

Receive a json OpenAPI spec -> return an api.yaml file

Feature issue: https://github.com/scanapi/scanapi/issues/12

But we need to discuss how we will integrate it into the main project. Some options that came into my mind:

Option 1

A new command like: $ scanapi init OPENAPI_PATH. And leave the main command as it is.

(we would need to investigate if it is easy to do that with Click, but I believe with groups is quite feasible.)

Option 2

A new command like: $ scanapi init OPENAPI_PATH and change the main command to something like $ scanapi run SPEC_PATH

(we would need to investigate if it is easy to do that with Click, but I believe with groups is quite feasible.)

Option 3

A new command like: $ scanapi-init OPENAPI_PATH. And leave the main command as it is

(This would be pretty easy to implement with Click)

Maybe generate instead of init, don't know 🤷‍♀️

I like the options 1 and 2. For me, the downside of 2 is that we would need to change the way it is now. And the downside of 1 is that for some cases we will use scanapi directly and for other with another command, which is not so intuitive and it is also not a pattern. Option 3 is easier but I dislike it because it is ugly 😂

Do you have more ideas? What do you think about this ones? @barbosa @gillianomenezes @djalmaaraujo @abreumatheus
ADR
opened by camilamaia 11
VSCode extension for ScanAPI IntelliSense
Given that ScanAPI already has a predefined yml structure, we could have a VSCode extension that autocompletes keys (endpoints, method, path, etc) based on where you are in the spec tree.

This would require further investigation to see what can be achieved but the following links should give some clarity:

https://code.visualstudio.com/api/language-extensions/overview

https://code.visualstudio.com/api/language-extensions/programmatic-language-features

Feature
opened by barbosa 11
There are some option to set verify=False to requests?
Environment

Operating System: Linux Xubuntu 16.04

Python version: 3.6

What you intend to do with scanapi ?

A want make a request to web server running locally with HTTPS enabled, but I need some way to make requests dont verify SSL.

I need something like that? requests.post(url='https://example.com', data={'bar':'baz'}, verify=False)

Expected behavior ?

There are some option for me reach that, saying to requests include 'verify=False'?

I'm trying to avoid this error:

Error to make request https://127.0.0.1:443/auth/authenticate. HTTPSConnectionPool(host='127.0.0.1', port=443): Max retries exceeded with url: /auth/authenticate (Caused by SSLError(SSLError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:777)'),))

Thanks in advance!

scanapi has a discord server so feel free to join and say 👋 hello. Maybe share the issue link?
Feature
opened by samueltcsantos 10
Update the README file with the new demo api version
Description

Update the sample yaml file

Motivation behind this PR?

What type of change is this?

Checklist

[ ] I have added a changelog entry / my PR does not need a new changelog entry. Instructions.

[ ] I have added/updated unit tests. Instructions.

[ ] New and existing unit tests pass locally with my changes. Instructions

[ ] I have self-documented code my changes by adding docstring(s) and comment(s). Instructions

[x] Current PR does not significantly decrease the code coverage and docstring coverage.

[ ] My code follows the style guidelines of this project.

[ ] I have run ScanAPI locally and manually tested my changes. Instructions.

Issue

Closes #368
First Contribution
opened by renato04 10
Add the link icon to copy anchor URL

Add the link icon to copy anchor URL

Anchor link was already implemented by PR https://github.com/scanapi/scanapi/pull/317. Now we need add an icon to each endpoint which the user can click and copy the anchor url.

Something similar of what github has:

The result would be something like this:

Related to: #260
Feature Reporter Hacktoberfest

opened by camilamaia 10
Add video to readme.md

Hi guys, recently @camilamaia has been create an video speak about ScanApi. will we add the video in readme on example session?

Video link: https://www.youtube.com/watch?v=JIo4sA8LHco&t=2s
ADR

opened by marcuxyz 10
ScanAPI spec from an OpenAPI specification
Refers to: [#12 ]

Added

Command convert, to convert a OpenAPI JSON file to a ScanAPI YAML friendly file;

Changed

Command scanapi to scanapi run;

Updated documentation to include changes and the new feature;
opened by abreumatheus 10
chore(deps): bump certifi from 2021.5.30 to 2022.12.7
Bumps certifi from 2021.5.30 to 2022.12.7.

Commits

9e9e840 2022.12.07

b81bdb2 2022.09.24

939a28f 2022.09.14

aca828a 2022.06.15.2

de0eae1 Only use importlib.resources's new files() / Traversable API on Python ≥3.11 ...

b8eb5e9 2022.06.15.1

47fb7ab Fix deprecation warning on Python 3.11 (#199)

b0b48e0 fixes #198 -- update link in license

9d514b4 2022.06.15

4151e88 Add py.typed to MANIFEST.in to package in sdist (#196)

Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

@dependabot rebase will rebase this PR

@dependabot recreate will recreate this PR, overwriting any edits that have been made to it

@dependabot merge will merge this PR after your CI passes on it

@dependabot squash and merge will squash and merge this PR after your CI passes on it

@dependabot cancel merge will cancel a previously requested merge and block automerging

@dependabot reopen will reopen this PR if it is closed

@dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually

@dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)

@dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)

@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

@dependabot use these labels will set the current labels as the default for future PRs for this repo and language

@dependabot use these reviewers will set the current reviewers as the default for future PRs for this repo and language

@dependabot use these assignees will set the current assignees as the default for future PRs for this repo and language

@dependabot use this milestone will set the current milestone as the default for future PRs for this repo and language

You can disable automated security fix PRs for this repo from the Security Alerts page.

dependencies
opened by dependabot[bot] 1
feat: change requests to httpx
Description

Change requests to httpx

Motivation behind this PR?

#208

What type of change is this?

Feature

Checklist

[x] I have added a changelog entry / my PR does not need a new changelog entry. Instructions.

[x] I have added/updated unit tests. Instructions.

[x] New and existing unit tests pass locally with my changes. Instructions

[x] I have self-documented code my changes by adding docstring(s) and comment(s). Instructions

[x] Current PR does not significantly decrease the code coverage and docstring coverage.

[x] My code follows the style guidelines of this project.

[x] I have run ScanAPI locally and manually tested my changes. Instructions.

[x] I have squashed my commits. Instructions.

Issue

Closes #208
opened by taconi 1
fix: custom variable evaluated when defined on the path (#508)
Description

Custom variable will be evaluated when defined in the path

Motivation behind this PR?

#508

What type of change is this?

Bug fix

Checklist

[X] I have added a changelog entry / my PR does not need a new changelog entry. Instructions.

[X] I have added/updated unit tests. Instructions.

[X] New and existing unit tests pass locally with my changes. Instructions

[ ] I have self-documented code my changes by adding docstring(s) and comment(s). Instructions

[X] Current PR does not significantly decrease the code coverage and docstring coverage.

[X] My code follows the style guidelines of this project.

[X] I have run ScanAPI locally and manually tested my changes. Instructions.

[X] I have squashed my commits. Instructions.

Issue

Closes #508
First Contribution
opened by taconi 0
Add --insecure flag in curl based on request options
Description

Add the --insecure flag in curl based on request options

Motivation behind this PR?

Closes #554

What type of change is this?

Bug fix

Checklist

[x] I have added a changelog entry / my PR does not need a new changelog entry. Instructions.

[x] I have added/updated unit tests. Instructions.

[x] New and existing unit tests pass locally with my changes. Instructions

[x] I have self-documented code my changes by adding docstring(s) and comment(s). Instructions

[x] Current PR does not significantly decrease the code coverage and docstring coverage.

[x] My code follows the style guidelines of this project.

[x] I have run ScanAPI locally and manually tested my changes. Instructions.

[x] I have squashed my commits. Instructions.

Issue

Closes #554
First Contribution
opened by Crocmagnon 1
curl generation doesn't take verify: false into account
Bug report

Environment

Operating System: not relevant

Python version: not relevant

Description of the bug

When using verify: false, the curl command generated without the --inscure / -k flag.

Expected behavior ?

The generated curl should include --insecure / -k when the request is not verified.

How to reproduce the the bug ?

endpoints: - name: scanapi-demo path: http://demo.scanapi.dev/api/ options: verify: false requests: - name: list_all_devs path: devs/ method: get

then

scanapi run

Then observe the genreated curl.

Anthing else we need to know?

curlify2 supports a verify argument on the to_curl method: https://github.com/marcuxyz/curlify2/blob/fc0fd402f77dea7c8c28840eeaa2886dc287f040/curlify2/curlify.py#L1
Bug Needs Triage
opened by Crocmagnon 1
Field Content is not being displayed properly on Chrome
Bug report

Environment

ScanAPI version: 2.7.0

Chrome Version 102.0.5005.61 (Official Build) (arm64)

Description of the bug

When generating a report, the field CONTENT of the RESPONSE section is not being displayed properly

Also, the copy button is not working

Expected behavior?

How to reproduce the bug ?

Can be reproduced by generating a report or checking the reports generated on the ScanAPI examples job on GitHub actions. For example https://github.com/scanapi/scanapi/actions/runs/2426475658. Open the report on Chrome.
Bug Reporter
opened by camilamaia 2

Releases(v2.8.0)

v2.8.0(Aug 11, 2022)
Added

Implement new key options to request and endpoint nodes #529

Source code(tar.gz)
Source code(zip)
v2.7.0(Jun 2, 2022)
Deprecated

Drops support for Python 3.6 since its EOL was reached out in December last year 549

Source code(tar.gz)
Source code(zip)
v2.6.2(Jun 1, 2022)
Added

Print test results summary in console #497

Fixed

Error when using list (or any other) comprehension in Python Code #515

Source code(tar.gz)
Source code(zip)
v2.6.1(Apr 12, 2022)
Changed

Implement new details to help users on visualize related request data. #506

Fixed

Fix the --browser flag not working on macOS #504

Error on running ScanAPI. ImportError: cannot import name 'soft_unicode' from 'markupsafe' #534

Source code(tar.gz)
Source code(zip)
v2.6.0(Aug 13, 2021)
Changed

Summary tests location to the top of the report #479

Fixed

Header table gets broken. #432

Source code(tar.gz)
Source code(zip)
v2.5.0(Jul 23, 2021)
Added

Enable 'vars' key at endpoint node. #328

Add --no-report flag. #325

Source code(tar.gz)
Source code(zip)
v2.4.0(Jun 11, 2021)
Added

Request name to report. #390

Show on report the scanapi version used to generate it. #386

Link icon to copy anchor URL. #398

Fixed

Error making request when request has no body and there is a report::hide_request::body configuration. #393

Source code(tar.gz)
Source code(zip)
v2.3.0(May 27, 2021)
Added

--version command to return current scanapi version. #372

Fixed

hide_response body. #375

Source code(tar.gz)
Source code(zip)
v2.2.0(Apr 22, 2021)
Added

Hide sensitive information in the URL Query Params #304

Anchor link for each request in the report to make it easily shareable. #317

Support to HTTP methods HEAD and OPTIONS #350

The retry key under requests to setup retry for requests. #298

Fixed

Curl command #330

Render body according to its request content type #331

Source code(tar.gz)
Source code(zip)
v2.1.0(Oct 6, 2020)
Added

Add a delay key option to perform a delay between each request. #266

Changed

Changed relative path to show absolute path to the report in CLI. #277

Considering - (dash) in variable names. #281

Moved bandit to dev section #285

Increased Test coverage for /scanapi/evaluators/spec_evaluator.py #291

Fixed

When there is no body specified, sending it as None instead of {}. #280

Removed unused imports. #294

Source code(tar.gz)
Source code(zip)
v2.0.0(Aug 25, 2020)
Added

JSON response is now properly rendered, instead of plain text. #213

The report page now has a favicon. #223

Bandit security audit tool. #219

Add Sphinx auto-documentation. #230

Add workflow to package/publish to Test PyPi. #239

Changed

Renamed api.(yaml|json) to scanapi.yaml. #222

Remove top-level api key in scanapi.yaml. #231

Renamed project-name, hide-request and hide-response to use underscore. #228

Changed command scanapi spec-file.yaml to scanapi run spec-file.yaml. #247

Moved Documentation from README.md to the website. #250

Local and global configuration. #254

Fixed

Updated language use in README.md and CONTRIBUTING.md plus fix broken links. #220

Removed unused sys import in scan.py and cleaned for PEP8 and spelling errors. #217

Hide body sensitive information. #238

Fix css issues with html template. #256

Fix when vars is declared and used in the same request.#257

Fix when evaluated value is not string. #257

Removed

APIKeyMissingError. #218

Source code(tar.gz)
Source code(zip)
v2.0.0-rc.1(Aug 25, 2020)
Added

JSON response is now properly rendered, instead of plain text. #213

The report page now has a favicon. #223

Bandit security audit tool. #219

Add Sphinx auto-documentation. #230

Add workflow to package/publish to Test PyPi. #239

Changed

Renamed api.(yaml|json) to scanapi.yaml. #222

Remove top-level api key in scanapi.yaml. #231

Renamed project-name, hide-request and hide-response to use underscore. #228

Changed command scanapi spec-file.yaml to scanapi run spec-file.yaml. #247

Moved Documentation from README.md to the website. #250

Local and global configuration. #254

Fixed

Updated language use in README.md and CONTRIBUTING.md plus fix broken links. #220

Removed unused sys import in scan.py and cleaned for PEP8 and spelling errors. #217

Hide body sensitive information. #238

Fix css issues with html template. #256

Fix when vars is declared and used in the same request.#257

Fix when evaluated value is not string. #257

Removed

APIKeyMissingError. #218

Source code(tar.gz)
Source code(zip)
v1.0.5rc2(Aug 25, 2020)
Added

JSON response is now properly rendered, instead of plain text. #213

The report page now has a favicon. #223

Bandit security audit tool. #219

Add Sphinx auto-documentation. #230

Add workflow to package/publish to Test PyPi. #239

Changed

Renamed api.(yaml|json) to scanapi.yaml. #222

Remove top-level api key in scanapi.yaml. #231

Renamed project-name, hide-request and hide-response to use underscore. #228

Changed command scanapi spec-file.yaml to scanapi run spec-file.yaml. #247

Moved Documentation from README.md to the website. #250

Local and global configuration. #254

Fixed

Updated language use in README.md and CONTRIBUTING.md plus fix broken links. #220

Removed unused sys import in scan.py and cleaned for PEP8 and spelling errors. #217

Hide body sensitive information. #238

Removed

APIKeyMissingError. #218

Source code(tar.gz)
Source code(zip)
v1.0.5(Jul 18, 2020)
Fixed

Status icons on report were not vertically centered #195

Source code(tar.gz)
Source code(zip)
v1.0.4(Jun 25, 2020)

Source code(tar.gz)
Source code(zip)
v1.0.3(Jun 25, 2020)
Added

MANIFEST.in

Source code(tar.gz)
Source code(zip)
v1.0.2(Jun 25, 2020)
Fixed

Fix for TemplateNotFound Error #197

Source code(tar.gz)
Source code(zip)
v1.0.1(Jun 25, 2020)
Fixed

Report example images not loading on PyPI #193

Source code(tar.gz)
Source code(zip)
v1.0.0(Jun 25, 2020)
Added

Add new HTML template #157

Tests key #152

-h alias for --help option #172

Test results to report #177

Add test errors to the report #187

Hides sensitive info in URL #185

CLI options explanation #189

Changed

Unified keys validation in a single method #151

Default template to html #173

Project name color on html reporter to match ScanAPI brand #172

Hero banner on README #180

Entry point to scanapi:main #172

--spec-path option to argument #172

Improve test results on report #186

Improve Error Message for Invalid Python code error #187

Handle properly exit errors #187

Update README.md #191

Fixed

Duplicated status code row from report #183

Sensitive information render on report #183

Removed

Console Report #175

Markdown Report #179

--reporter option #179

Source code(tar.gz)
Source code(zip)
v0.1.0(May 14, 2020)
Added

Automated pypi deploy - #144

Source code(tar.gz)
Source code(zip)
v0.0.19(May 11, 2020)
Added

PATCH HTTP method - #77

Ability to have API spec in multiples files - #125

CLI --config-path option - #128

CLI --template-path option - #126

GitHub Action checking for missing changelog entry - #134

Changed

Make markdown report a bit better - #96

base_url keyword to path #116

namespace keyword to name #116

method keyword is not mandatory anymore for requests. Default is get #116

Replaced hide key on report config by hide-request and hide-response #116

Moved black check from CircleCI to github actions #136

Fixed

Cases where custom var has upper case letters #99

Removed

Request with no endpoints #116

Source code(tar.gz)
Source code(zip)
v0.0.18(Jan 2, 2020)
Changed

Return params/headers None when request doesn't have params/headers #87

Fixed

Report-example image not loading on PyPi #86

Source code(tar.gz)
Source code(zip)
v0.0.17(Dec 18, 2019)
Add PyPI Test section to CONTRIBUTING.md

Add templates to pypi package - fix https://github.com/camilamaia/scanapi/issues/84

Source code(tar.gz)
Source code(zip)
v0.0.16(Dec 18, 2019)
Fix No module named 'scanapi.tree' https://github.com/camilamaia/scanapi/issues/82

Source code(tar.gz)
Source code(zip)
v0.0.15(Dec 14, 2019)
Update Documentation

Increase coverage

Fix join of urls to keep the last slash

Remove requirements files and put every dependency under setup.py

Remove dcvars key

Using dot notation to access responses inside api spec

Rename option report_path to output_path

Reporter option -r, --reporter [console|markdown|html]

CodeCov Setup

CircleCI Setup

Source code(tar.gz)
Source code(zip)
v0.0.14(Oct 9, 2019)

Add math, time, uuid and random libs to be used on api spec
Source code(tar.gz)
Source code(zip)
v0.0.13(Oct 7, 2019)

Source code(tar.gz)
Source code(zip)
v0.0.12(Aug 14, 2019)

Using env variables from os
Source code(tar.gz)
Source code(zip)
v0.0.11(Aug 9, 2019)

Add docker file
Source code(tar.gz)
Source code(zip)
v0.0.10(Aug 9, 2019)
Fix vars interpolation

Add logging

Option to hide headers fields

Source code(tar.gz)
Source code(zip)

Owner

ScanAPI

Automated Integration Testing and Live Documentation for your API

GitHub Repository https://scanapi.dev

Automated Integration Testing and Live Documentation for your API

Related tags

Overview

Contents

Requirements

How to install

Basic Usage

Documentation

Examples

Contributing

Comments

Description

Motivation behind this PR?

What type of change is this?

Checklist

Issue

Architecture Decision Review - ADR

Publish Sphinx Documentation

Architecture Decision Review - ADR

Option 1

Option 2

Option 3

Environment

What you intend to do with scanapi ?

Expected behavior ?

Description

Motivation behind this PR?

What type of change is this?

Checklist

Issue

Add the link icon to copy anchor URL

Refers to: [#12 ]

Added

Changed

Description

Motivation behind this PR?

What type of change is this?

Checklist

Issue

Description

Motivation behind this PR?

What type of change is this?

Checklist

Issue

Description

Motivation behind this PR?

What type of change is this?

Checklist

Issue

Bug report

Environment

Description of the bug

Expected behavior ?

How to reproduce the the bug ?

Anthing else we need to know?

Bug report

Environment

Description of the bug

Expected behavior?

How to reproduce the bug ?

Releases(v2.8.0)

v2.8.0(Aug 11, 2022)

Added

v2.7.0(Jun 2, 2022)

Deprecated

v2.6.2(Jun 1, 2022)

Added

Fixed

v2.6.1(Apr 12, 2022)

Changed

Fixed

v2.6.0(Aug 13, 2021)

Changed

Fixed

v2.5.0(Jul 23, 2021)

Added

v2.4.0(Jun 11, 2021)

Added

Fixed

v2.3.0(May 27, 2021)