README.md

Continuously test your web services

Post-deployment testing with Assertible

Assertible extends your CI pipeline to provide automated post-deployment API testing. This repo will show you how to run integration tests against your web app after deploying from CI.

Don't have an Assertible account yet? Sign up for free.

How it works

1. Send a deployment to the Assertible API
2. View the result in a GitHub status check (optional)

Start by sending a deployment to the Assertible API after you deploy your app from CI. This will initiate integration tests to run on your live web app, and reports any test failures.

When you connect Assertible to a GitHub repo, the post deployment test results will show as a status check on your commits and pull requests.

Send a deployment to the Assertible API

The Deployments API is used to run integration tests on your app after a deployment. Tests can be run on different environments, like staging or qa, by making a simple POST request:

curl -u $ASSERTIBLE_TOKEN: -XPOST "https://assertible.com/deployments" -d'{
    "service": "'"${SERVICE}"'",
    "environmentName": "'"${ENVIRONMENT}"'",
    "version": "'"${VERSION}"'",
    # Optional
    "ref": "'"${COMMIT_ID}"'",
    "github": true
}'

That's it! When you make that request, tests will be run against your API to validate the new deployment.

Check out the example configurations for details on integrating the script with your CI/CD provider, like TravisCI or Wercker.

View the result in a GitHub status check

When you connect Assertible to a GitHub repo, status checks will be shown for test results triggered by deployments. Setting up this part is easy, just sign in to Assertible, and connect one of your web services to a repo.

Assertible will send a status check to GitHub when you send a deployment event to the API. If any of the tests fail, a failing status check will show on your commits, and a passing status check will show if all tests pass.

Example configurations

Below are some examples for integrating Assertible deployments with various CI providers.

• Heroku (website)
• Travis CI (website)
• Circle CI (website)
• Wercker (website)
• Additional resources
• Status badges!
• Example Projects

Heroku

If you're using Heroku Review Apps, this integration will work out of the box with no additional configuration. Just connect Assertible to a GitHub repo that has Review Apps enabled, and open a PR. You should see a status check with the result of your API tests. Learn how to enable this for your Heroku app here

Travis CI

Note that the examples below assume that you have environment variables set. See the environment variables section.

If you deploy a website or API from Travis-CI (especially if you're using the deploy or after_success steps), then it will be easy to trigger a deployment event to run your Assertible tests. The sections below describe some common use-cases:

Sections

• Example .travis.yml
• Using the after_deploy step
• Using after_script or after_success

Example Travis config

You can see a runnable .travis.yml in the repo here:

• https://github.com/assertible/deployments/blob/master/.travis.yml

Note: You can just copy the two lines below into your existing configuration, if you have one. Otherwise, continue reading to determine which setup will work best.

after_deploy

If you use the deploy step in your Travis configuration then you can send a deployment event from the after_deploy step, like this:

after_deploy:
  - |
    curl -u $ASSERTIBLE_TOKEN: -XPOST "https://assertible.com/deployments" -d'{
        "service": "'"${ASSERTIBLE_SERVICE}"'",
        "environmentName": "'"${ENVIRONMENT}"'",
        "version": "'"${TRAVIS_COMMIT}"'",
        "ref": "'"${TRAVIS_COMMIT}"'",
        "github": true
    }'

after_success

If your .travis.yml runs a deployment during the after_success step, then you have two options:

• Add the following lines to the end of your existing after_success script, or
• Copy the following lines to the after_script step in your .travis.yml.

Example in the after_script step:

after_script:
  - |
    curl -u $ASSERTIBLE_TOKEN: -XPOST "https://assertible.com/deployments" -d'{
        "service": "'"${ASSERTIBLE_SERVICE}"'",
        "environmentName": "'"${ENVIRONMENT}"'",
        "version": "'"${TRAVIS_COMMIT}"'",
        "ref": "'"${TRAVIS_COMMIT}"'",
        "github": true
    }'

Read more about after_success step here

Circle CI

Note that the examples below assume that you have environment variables set See the environment variables section.

If you deploy a website or API from Circle CI (especially if you're using the deployment step), then it will be easy to trigger a deployment event to run your integration tests. The sections below describe the most common use-cases:

Sections

• Example circle.yml
• Using the deployment step

Example CircleCI config

You can see a runnable circle.yml in the repo here:

• https://github.com/assertible/deployments/blob/master/circle.yml

deployment

If your circle.yml runs a deployment step, add the following lines to the end of the commands section:

deployment:
  production:
    branch: master
    commands:
      # - deploy your app normally here
      - |
        curl -u $ASSERTIBLE_TOKEN: -XPOST "https://assertible.com/deployments" -d'{
            "service": "'"${ASSERTIBLE_SERVICE}"'",
            "environmentName": "'"${ENVIRONMENT}"'",
            "version": "'"${CIRCLE_SHA1}"'",
            "ref": "'"${CIRCLE_SHA1}"'",
            "github": true
        }'

Read more about deployment step here: https://circleci.com/docs/configuration/#deployment

Wercker

Note that the examples below assume that you have environment variables set See the environment variables section.

If you deploy your API or website from Wercker (especially if you're using the deployment step), then it will be easy to run integration tests after a deployment. The sections below describe the most common workflows:

Sections

• Example wercker.yml
• Using the deployment step

Example Wercker config

You can see a runnable wercker.yml in the repo here.

deploy step

If your wercker.yml runs a deployment step, add the following lines as the very last step in a script:

deploy:
  steps:
    # This is where you would normally run your deployment. Right
    # after this, we will tell Assertible about the deployment, and
    # tests will be run against the app.
    - script:
      code:
        - |
          curl -u $ASSERTIBLE_TOKEN: -XPOST "https://assertible.com/deployments" -d'{
              "service": "'"${ASSERTIBLE_SERVICE}"'",
              "environmentName": "'"${ENVIRONMENT}"'",
              "version": "'"${WERCKER_GIT_COMMIT}"'",
              "ref": "'"${WERCKER_GIT_COMMIT}"'",
              "github": true
          }'

Read more about deployment step here.

Environment variables

The examples above assume you have some environment variables set:

• ASSERTIBLE_TOKEN
• ASSERTIBLE_SERVICE

You can get this information from the Deployments tab of your web service in the Assertible dashboard.

Travis CI

Set these environment variables in your Travis-CI repository settings.

CircleCI CI

Set these environment variables in your Circle CI repository settings.

Wercker

Set these environment variables in your Wercker project settings.

Additional resources

These links provide more information on the underlying technology and services that make this work:

• Assertible - Getting Started
• Setting up Assertible and GitHub Deployments
• Deployments API documentation

Alternatives

Sometimes you don't use GitHub, or sending deployment events isn't always possible. Assertible also supports a standalone Trigger URL that you can use to run your tests from outside the Assertible dashboard. For more information, see the documentation

Status Badges

Assertible has status badges for your web services and tests to display the current state of your application. The badges can be retrieved from within your Assertible dashboard. Here's what they look like:

Nice! Pick yours up today and add it to your repository -- or learn more in the documentation

Example projects

There are some open source projects using Assertible with this configuration; if you're a visual learner then one of these might be helpful:

• Node.js example app This repo provides an example of a complete continuous integration, deployment, and post-deployment testing pipeline using a Node.js example app. Check out the tutorial

• Ruby API example This is an example of an automated post-deployment testing pipeline on staging and production environments, with a sample Ruby API. The project uses Codehsip, Heroku, and assertible.

• Go API example on Heroku This example uses a Go API that is deployed to Heroku and Review Apps. Since Heroku apps work out-of-the-box, there's no need for a script. Check out the blog post

• reichertbrothers.com reichertbrothers.com is the website for a Haskell consulting company. The website is deployed to GitHub Pages from a Travis-CI build. Once the site has been successfuly deployed, a deployment event is triggered and Assertible's post-deployment tests will run.

• CheckAFlip CheckAFlip is a tool for quickly learning the best price at which to buy or sell any item. The app is deployed from Heroku and, after deploying, Heroku sends a deployment success event and Assertible test's get run.

Have an open source project using Assertible for post deployment testing? Open a PR to add it to the list, or open an issue!

License

All of the code snippets in this repository are licensed under MIT. View the license

---

assertible.com  ·  GitHub @assertible  ·  Twitter @AssertibleApp