Jenkins

A declarative pipeline that calls an endpoint and fails the build if the answer is wrong.

pipeline {
    agent any

    stages {
        stage('Health check') {
            steps {
                sh 'npx --yes @atrahasis/cli GET https://api.example.com/health -a "status eq 200"'
            }
        }
    }
}

If the status is not 200, atra exits non-zero, the sh step fails, and the build goes red. That exit code is the entire integration.

Jenkins agents vary far more than hosted runners do, so pick whichever of these matches yours. All three were run against a real Jenkins instance and all three work.

sh 'npx --yes @atrahasis/cli GET $base_url/health -a "status eq 200"'

stage('Health check') {
    tools { nodejs 'node-22' }
    steps {
        sh 'npx --yes @atrahasis/cli GET $base_url/health -a "status eq 200"'
    }
}

stage('Health check') {
    agent { docker { image 'node:22-alpine' } }
    steps {
        sh 'npx --yes @atrahasis/cli GET $base_url/health -a "status eq 200"'
    }
}

sh 'curl -fsSL https://cli.atrahasis.dev | sh'
sh 'atra GET $base_url/health -a "status eq 200"'

Flows and load specs read their values from an Atrahasis environment. A variable marked as a secret with its source set to OS is read from an operating system environment variable named exactly like the key, so a key of base_url needs an environment variable called base_url.

In Jenkins that bridge is one line. Store the value as a Secret text credential, then bind it in an environment block using the key as the variable name.

pipeline {
    agent any

    environment {
        base_url = credentials('atrahasis-base-url')
    }

    stages {
        stage('Run flow') {
            steps {
                sh 'npx --yes @atrahasis/cli run -f logout -e dev'
            }
        }
    }
}

The credential ID can be anything, here atrahasis-base-url. What matters is the name on the left of the assignment, because that is what atra looks up. Agents are almost always Linux, where environment variable names are case-sensitive, so copy the key from the app exactly.

Binding a credential for one stage only

If you would rather not expose the value to the whole pipeline, use withCredentials around the step instead. Same outcome, narrower scope.

steps {
    withCredentials([string(credentialsId: 'atrahasis-base-url', variable: 'base_url')]) {
        sh 'npx --yes @atrahasis/cli run -f logout -e dev'
    }
}

Flows and load specs are built in Atrahasis, which writes them as plain files. Commit that folder and let the pipeline check it out. Most teams keep tests in their own repository, since several pipelines often want the same flow and tests outlive any one release.

Wrap the checkout in a dir block so the clone lands in its own folder and atra runs inside it.

stage('Run flow') {
    steps {
        dir('flows') {
            git url: 'https://github.com/my-org/api-flows.git', branch: 'main'
            sh 'npx --yes @atrahasis/cli run -f logout -e dev'
        }
    }
}

For a private repository add a credential: git url: '...', branch: 'main', credentialsId: 'github-token'.

Where atra runs matters

atra reads the flow group from the folder it is run in. If the group sits at the root of the checked-out repository, run inside that folder and leave the group name out. If several groups live side by side in one repository, run from the parent and name the group as the first argument: run checkout-flows -f signup -e dev.

1. A request with assertions

Best after a deploy, to prove the thing answered. Every assertion has to pass or the stage fails.

stage('Health check') {
    steps {
        sh '''
            npx --yes @atrahasis/cli GET $base_url/health \
                -a "status eq 200" \
                -a "$.status eq UP" \
                -a "response_time lt 2000"
        '''
    }
}

The triple-quoted block keeps a long command readable. It has to be single quotes: with triple double quotes Groovy would try to interpolate $base_url and $.status itself.

2. A flow from the app

A flow chains requests and passes values between them, such as logging in and reusing the token. Drop -f to run every flow in the group.

stage('Flow') {
    steps {
        dir('flows') {
            git url: 'https://github.com/my-org/api-flows.git', branch: 'main'
            sh 'npx --yes @atrahasis/cli run -f logout -e dev'
        }
    }
}

3. A load test from the app

Same spec you built in the app, run headless. Pick the profile with -t, and drop -s to run every spec in the group.

stage('Load test') {
    steps {
        dir('loads') {
            git url: 'https://github.com/my-org/api-loads.git', branch: 'main'
            sh 'npx --yes @atrahasis/cli run -s logout -t load -e dev'
        }
    }
}

Load tests are long and noisy compared to the rest of a pipeline. A common arrangement is to keep requests and flows on every build and give the load test its own job on a cron trigger.

All three jobs together, with the test repositories checked out and the credential bridged. This is close to the pipeline the examples above were verified against.

pipeline {
    agent any

    environment {
        // The one rule: put the value in an OS environment variable and
        // match the key name. environments.json reads base_url back from
        // here, so the same flow runs unchanged on a laptop and on an agent.
        base_url = credentials('atrahasis-base-url')
    }

    stages {
        stage('Build') {
            steps {
                sh './mvnw -B -ntp -DskipTests package'
            }
        }

        stage('Health check') {
            steps {
                sh '''
                    npx --yes @atrahasis/cli GET $base_url/health \
                        -a "status eq 200" \
                        -a "$.status eq UP" \
                        -a "response_time lt 2000"
                '''
            }
        }

        stage('Flow') {
            steps {
                dir('flows') {
                    git url: 'https://github.com/my-org/api-flows.git', branch: 'main'
                    sh 'npx --yes @atrahasis/cli run -f logout -e dev'
                }
            }
        }

        stage('Load test') {
            steps {
                dir('loads') {
                    git url: 'https://github.com/my-org/api-loads.git', branch: 'main'
                    sh 'npx --yes @atrahasis/cli run -s logout -t load -e dev'
                }
            }
        }
    }
}

atra exits 0 when every check passed and non-zero when any of them did not. A sh step fails on a non-zero exit status, so a failed assertion in a request, a failed step in a flow and a breached threshold in a load test all fail the stage and stop the build. No wrapper script and no parsing of the console output.

To let later stages run anyway, the usual catchError or a post block applies as it would around any other command. Reach for it sparingly: a stage that cannot fail the build is a stage nobody reads.