What Is Step CI and How to Use It

Automating API testing ensures quality and efficiency. Step CI, an open-source API testing framework, simplifies this process with a developer-friendly, YAML-based approach. Whether you're a seasoned developer or just starting, Step CI integrates seamlessly into your CI/CD pipelines, offering flexibility and power. In this article, we explore Step CI’s features, setup, and usage, while comparing it with tools like Apidog.

What Is Step CI? Understanding the Basics

Step CI is an open-source, lightweight API testing framework designed to automate and validate HTTP-based APIs. Unlike traditional testing tools that require extensive coding, Step CI uses YAML-based workflows, making it accessible to developers and non-developers alike. Its primary goal is to streamline API testing within CI/CD pipelines, ensuring consistent and reliable API performance.

Key features of Step CI include:

• YAML-based Configuration: Define test workflows in simple, human-readable YAML files.
• CI/CD Integration: Seamlessly integrate with tools like GitHub Actions, Jenkins, and GitLab CI.
• Extensibility: Support for custom plugins and integrations.
• Cross-Protocol Support: Test HTTP, gRPC, and WebSocket APIs.
• Open-Source: Freely available under the MIT license, with an active community on GitHub.

Compared to tools like Apidog, which offers a visual interface for API testing, Step CI focuses on script-based automation, ideal for developers who prefer code-driven workflows. While Apidog excels in user-friendly test case design, Step CI’s strength lies in its flexibility for complex, automated testing scenarios.

Why Use Step CI? Benefits for Developers

Step CI addresses common pain points in API testing, such as manual validation, complex scripting, and pipeline integration. Here’s why developers choose Step CI:

1. Simplified Workflow Creation: YAML-based tests reduce the need for extensive programming knowledge.
2. Pipeline-Friendly: Integrates with CI/CD tools, enabling automated testing on every commit.
3. Scalability: Handles small projects to enterprise-grade APIs with ease.
4. Cost-Effective: As an open-source tool, it’s free, unlike some premium features in Apidog.
5. Community Support: Regular updates and contributions via GitHub ensure longevity.

For instance, a team using GitHub Actions can trigger Step CI tests automatically, catching API issues before deployment. In contrast, Apidog’s CLI supports CI/CD but emphasizes visual test management, which may suit teams prioritizing ease of use over script customization.

Getting Started with Step CI: Installation and Setup

To use Step CI, you need a basic setup. This section guides you through installation and configuration, ensuring you’re ready to write your first test.

Prerequisites

Before installing Step CI, ensure you have:

• Node.js (version 14 or higher) installed.
• A code editor like VS Code.
• Basic knowledge of YAML and HTTP APIs.
• A terminal or command-line interface.

Step 1: Install Step CI

Step CI is available via npm, Node.js’s package manager. Open your terminal and run:

npm install -g @stepci/cli

Verify the installation by checking the version:

stepci --version

This confirms Step CI is installed globally. If you encounter errors, ensure Node.js is correctly set up.

Step 2: Initialize a Step CI Project

Create a new directory for your project and initialize Step CI:

mkdir stepci-project
cd stepci-project
stepci init

This generates a stepci.yml file, the core configuration for your tests. The file includes a default structure:

version: "1.1"
name: Example Workflow
tests:
  example:
    steps:
      - name: GET request
        http:
          url: https://api.example.com
          method: GET

Step 3: Install Apidog for Complementary Testing

While Step CI handles script-based testing, Apidog’s visual interface complements it for manual test case design. Download Apidog from Apidog.com and install it. Create an account to access its free features, such as API documentation and test case management.

Writing Your First Step CI Test

With Step CI installed, let’s create a test for a sample API. We’ll use a public API, such as JSONPlaceholder, to demonstrate.

Step 1: Define the Test Workflow

Edit the stepci.yml file to test a GET request to retrieve a post:

version: "1.1"
name: JSONPlaceholder Test
tests:
  getPost:
    steps:
      - name: Fetch Post
        http:
          url: https://jsonplaceholder.typicode.com/posts/1
          method: GET
          check:
            status: 200
            body:
              id: 1
              userId: 1

This workflow:

• Sends a GET request to /posts/1.
• Verifies the response status is 200.
• Checks that the response body contains id: 1 and userId: 1.

Step 2: Run the Test

Execute the test using:

stepci run stepci.yml

The output shows the test results:

✔ Test: getPost
  ✔ Step: Fetch Post
All tests passed!

If the test fails, Step CI provides detailed error messages, such as mismatched status codes or body content.

Step 3: Add Assertions

Enhance the test with additional assertions. Update stepci.yml to validate response headers:

version: "1.1"
name: JSONPlaceholder Test
tests:
  getPost:
    steps:
      - name: Fetch Post
        http:
          url: https://jsonplaceholder.typicode.com/posts/1
          method: GET
          check:
            status: 200
            headers:
              content-type: application/json; charset=utf-8
            body:
              id: 1
              userId: 1

Run the test again to ensure all assertions pass.

Integrating Step CI with CI/CD Pipelines

Step CI shines in CI/CD environments, automating API tests on code changes. Let’s integrate it with GitHub Actions, a popular CI/CD platform.

Step 1: Create a GitHub Repository

Push your Step CI project to a GitHub repository:

git init
git add .
git commit -m "Initial Step CI project"
git remote add origin <your-repo-url>
git push -u origin main

Step 2: Set Up GitHub Actions

Create a .github/workflows/ci.yml file in your repository:

name: API Tests
on:
  push:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - name: Install Step CI
        run: npm install -g @stepci/cli
      - name: Run Step CI Tests
        run: stepci run stepci.yml

This workflow:

• Triggers on pushes to the main branch.
• Sets up Node.js.
• Installs Step CI.
• Runs the tests defined in stepci.yml.

Step 3: Test the Pipeline

Commit and push the workflow file:

git add .github/workflows/ci.yml
git commit -m "Add GitHub Actions workflow"
git push

Check the GitHub Actions tab in your repository to view the test results. If tests fail, review the logs for debugging.

Step 4: Enhance with Apidog

Use Apidog to generate test cases visually, then export them as OpenAPI specifications. Import these into Step CI for automated testing, combining Apidog’s ease of use with Step CI’s automation power.

Advanced Step CI Features

Step CI offers advanced features for complex testing scenarios. Let’s explore a few.

Parameterization

Reuse test data across steps using variables. Update stepci.yml:

version: "1.1"
name: Parameterized Test
env:
  baseUrl: https://jsonplaceholder.typicode.com
tests:
  getPost:
    steps:
      - name: Fetch Post
        http:
          url: ${{ env.baseUrl }}/posts/1
          method: GET
          check:
            status: 200

The baseUrl variable simplifies URL management.

Chaining Requests

Test dependent APIs by chaining requests. For example, create a post and then retrieve it:

version: "1.1"
name: Chained Requests
tests:
  createAndGetPost:
    steps:
      - name: Create Post
        http:
          url: https://jsonplaceholder.typicode.com/posts
          method: POST
          body:
            title: Test Post
            body: This is a test
            userId: 1
          check:
            status: 201
          capture:
            postId: body.id
      - name: Fetch Created Post
        http:
          url: https://jsonplaceholder.typicode.com/posts/${{ steps.createPost.postId }}
          method: GET
          check:
            status: 200

The capture keyword stores the id from the first response for use in the second request.

Custom Plugins

Extend Step CI with custom plugins. Create a JavaScript file, custom-plugin.js:

module.exports = {
  name: 'customHeader',
  async run(context, options) {
    context.request.headers['X-Custom-Header'] = options.value;
  }
};

Register the plugin in stepci.yml:

version: "1.1"
name: Custom Plugin Test
plugins:
  customHeader: ./custom-plugin.js
tests:
  getPost:
    steps:
      - name: Fetch Post
        http:
          url: https://jsonplaceholder.typicode.com/posts/1
          method: GET
          customHeader:
            value: TestValue
          check:
            status: 200

Run the test to apply the custom header.

Step CI vs. Apidog: A Comparison

Both Step CI and Apidog excel in API testing, but they serve different needs. Here’s a comparison:

For example, a developer automating tests in Jenkins might prefer Step CI’s YAML workflows, while a QA engineer designing test cases visually might choose Apidog. Combining both tools leverages Step CI’s automation with Apidog’s intuitive design.

Best Practices for Step CI

To maximize Step CI’s potential, follow these best practices:

• Organize Workflows: Group related tests into separate YAML files.
• Use Version Control: Store stepci.yml in Git for collaboration.
• Validate Responses: Include comprehensive assertions for status, headers, and body.
• Monitor Performance: Add performance checks, such as response time, using custom plugins.
• Document Tests: Comment YAML files for clarity, e.g., # Test GET endpoint.

Troubleshooting Common Issues

Encountering issues with Step CI? Here are common problems and solutions:

• Test Fails with 404: Verify the API URL and endpoint.
• YAML Syntax Error: Use a YAML linter to check syntax.
• CI Pipeline Fails: Check Node.js version compatibility in your CI environment.
• Slow Tests: Optimize by reducing unnecessary assertions or parallelizing tests.

Conclusion: Elevate Your API Testing with Step CI

Step CI transforms API testing with its YAML-based, CI/CD-friendly approach. From simple GET requests to complex chained workflows, it empowers developers to automate testing efficiently. By integrating with tools like GitHub Actions and complementing platforms like Apidog, Step CI ensures robust API validation. Start using Step CI today by installing it from npm and exploring its documentation at StepCI. For a visual testing companion, download Apidog for free. Share your Step CI experiences in the comments or join the GitHub community to contribute.