Automate API Testing with Hoppscotch and GitHub Actions

API testing can often feel repetitive, especially when you are manually verifying endpoints every time there’s a change. It’s easy to overlook a detail or get bogged down in the process. Plus, as your codebase grows, this manual testing process becomes more time-consuming and prone to errors. In situations like these, you can’t help but wonder how much easier it would be if things could be automated. And hey, it's 2025, automation is totally within our reach. With the right setup, you can now run tests automatically every time there's an update to your code, making sure everything’s still working as it should. And with Hoppscotch, integrating automated API testing into your CI/CD pipeline comes in a snap.

Hoppscotch is an open-source, self-hostable platform that makes API development and testing ridiculously easy. It’s quick to get started, no account required, just hop onto hoppscotch.io, create your request, and hit send. Simple as that.

Check out Hoppscotch 🛸

But today, we’re going to explore another cool perk of using Hoppscotch and that is leveraging Hoppscotch CLI to automatically execute API requests stored in your collection.

Hoppscotch CLI 📟

Hoppscotch offers various editions, and one of them is the CLI, which lets you run your API requests remotely from the comfort of your terminal. If you're looking to create a setup and test your APIs locally, check out the pre-requisites described here based on your system configurations, verify the node version, and install the latest version of Hoppscotch CLI into your machine with a simple command:

npm i -g @hoppscotch/cli

There are two ways to run your collection using the Hoppscotch CLI:

1️⃣ Using JSON Exports: Export your collection and associated environment in JSON format and pass it alongside the hopp test command to get the test summary:

hopp test [-e <environment file>] <hoppscotch collection file>

2️⃣ Using IDs: Every time you create a collection or an environment, Hoppscotch assigns a unique ID to them. You can use these IDs to reference your collection when running tests via the CLI. But to connect your instance account with Hoppscotch, you also need to provide a personal access token, which is super simple to generate in Hoppscotch. Follow the steps here to generate the token. And if you're using a self-hosted instance of Hoppscotch, don't forget to provide the server URL in the command:

hopp test [-e <environment id>] <hoppscotch collection id> [--token <access_token>] [--server <server url>]

Hoppscotch + GitHub Actions 🔁

Let’s take a simple Express application as an example. This app defines routes to perform CRUD operations on quotes, exposed to localhost:5000. We'll also create a collection within Hoppscotch that includes APIs for fetching all quotes from the database, fetching a specific quote by ID, adding a new quote to the list, updating an existing quote, and removing a quote. To avoid repeatedly typing the URL and paths, we'll also create an environment so we can refer to them via variables.
To get familiar with the codebase, refer to this repository. If you want to understand the logic behind each API request, follow this blog.

Now that we have the basics in place, let's take things up a notch by introducing GitHub Actions. GitHub Actions allows us to automate various tasks like running tests, building, and deploying our application directly from our repository. In this blog, we’ll specifically focus on the CI (Continuous Integration) part to automate API testing for our Express app.

🔑 Generating a Personal Access Token

In this example, we’ll be running our collection using IDs, and to do that successfully, we need a Personal Access Token. Head over to your profile page in Hoppscotch, then switch to the “Tokens” tab. Click on “Generate new token,” give it a label, choose an expiration date, and click “Generate Token.” Be sure to save the token somewhere safe, as you won’t be able to see it ever again.

Now that we have our token, let’s ensure it stays secure in our pipeline. To do this, we’ll store it as an action secret. Go to your GitHub repository, then navigate to Settings > Secrets and Variables > Actions > New Repository Secret. Give it a meaningful name (e.g. HOPPSCOTCH_PERSONAL_ACCESS_TOKEN) and paste in your Personal Access Token.

🆔 Collecting Collection and Environment IDs

One of the easiest ways to fetch both the collection and environment IDs is by clicking on the Runner icon that appears when you hover over your collection. Switch to the CLI tab in the modal, and you’ll find a command ready to use. If you select the option to include environment properties, the environment ID will be appended to the command as well. Cool, right?

But, if you prefer to collect the IDs manually, you can find them under the "Properties" menu of both the collection and environment.

We’ll use these IDs in the command within our pipeline. Below is an example:

hopp test cm5wuvaf700jwwdopsb68uoic -e cm47dw3jy002d3f238uk4yfr1 --token <access_token>

▶️ Creating the CI Workflow

Since this application isn't deployed yet and is only a sample for API testing, as mentioned earlier, we'll focus on crafting a CI (Continuous Integration) pipeline to validate the functionality of the API endpoints defined in quotes.js.

Workflow files use YAML (a data serialization language) syntax. To learn more about YAML, check out this YAML in Y Minutes tutorial. For a detailed explanation of different jobs you can define in a GitHub Actions workflow, refer to the GitHub Actions Workflow Syntax documentation.

To get started, create a .github/workflows directory in your project root. Inside this folder, create a YAML file (e.g., quotes-api.yml) to define the pipeline instructions. This file will specify the steps and jobs required to automate our workflows.

on:
  push:
    branches:
      - main  
  pull_request:
    branches:
      - main 

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '20'  

      - name: Install dependencies
        run: |
          npm install

      - name: Install Hoppscotch CLI
        run: |
          npm i -g @hoppscotch/cli

      - name: Verify Hoppscotch version
        run: |
          hopp --ver

      - name: Start the server
        run: |
          nohup npm start & 
          echo $! > server.pid
          sleep 10

      - name: Wait for server to be ready
        run: |
          until curl -s http://127.0.0.1:5000; do
            echo "Waiting for server..."
            sleep 5
          done

      - name: Run Hoppscotch tests
        run: |
          hopp test cm5wuvaf700jwwdopsb68uoic -e cm47dw3jy002d3f238uk4yfr1 --token $HOPPSCOTCH_PERSONAL_ACCESS_TOKEN
        env:
          HOPPSCOTCH_PERSONAL_ACCESS_TOKEN: ${{ secrets.HOPPSCOTCH_PERSONAL_ACCESS_TOKEN }}

      - name: Stop the server
        run: |
          kill $(cat server.pid) 
          rm server.pid

The workflow is pretty straightforward, and it covers all the key steps needed to automate your API testing with Hoppscotch in your CI pipeline. Every time new changes are introduced to the codebase or when a new PR is created for the main branch, this workflow will run automatically.

First, we check out the code and set up the Node.js environment, ensuring all dependencies are installed. Next, we install the Hoppscotch CLI globally to enable testing via the command line. After confirming the Hoppscotch version, we start the server that will host the API for testing. The workflow waits until the server is fully up and running before executing the actual Hoppscotch tests.

Here, you can see Hoppscotch’s power in action, using the hopp test command to run the API collection tests with a personal access token, securely referenced through GitHub Actions secrets. Finally, the server is stopped once the tests are completed.

Tip 💡

You can even generate a JUnit report of the test summary to integrate seamlessly with your CI/CD pipelines or for structured test result tracking. Just add the --reporter-junit flag to your existing hopp test command and specify the path where the file should be saved. If no path is mentioned, the report will be saved in the working directory by default.

hopp test <file_path_or_id> [-e <file_path_or_id>] --reporter-junit [path]

---

And that’s it! You can commit your changes and push the code to see the results in action. You can also view the logs of the pipeline I’ve set up for the quotes application here. Pretty simple, right?

If you prefer a graphical interface over the command line then check out the GUI version of our collection runner. It offers an intuitive way to run your collections directly from the Hoppscotch web interface. Have a look at this video and refer the documentation for the same.

So go ahead, integrate Hoppscotch into your automation workflow and simplify API testing for yourself and your team. Thank you for supporting Hoppscotch 💚. We’re always looking to improve, and your feedback makes a difference. If you have any suggestions or run into issues, feel free to reach out at [e-mail], or visit our GitHub repository to open an issue or chat with us 💬.