CI/CD Integration Guide

VibeView runs your mobile tests on cloud iOS simulators and Android emulators (and Apple TV and Android TV devices) as part of your CI/CD pipeline. This guide walks through the pipeline from building your app to reading the results. It is the starting point for integration: see CLI Reference, CI Testing and GitHub Checks for the detailed reference.

Prerequisites

Before starting, make sure you have:

• A VibeView account with an API token (generate one at Settings > API token)
• Test groups in VibeView, tagged for CI (for example smoke), or plain-English test steps for the AI agent (beta)
• A way to build your app: your own CI build (a simulator .app for iOS, an .apk for Android), or cloud builds
• Node.js 20 or later
• The VibeView CLI installed:

npm install -g vibeview

Pipeline Overview

Every CI/CD integration follows the same steps:

Build App  -->  Upload  -->  Run  -->  Results
   |              |            |           |
 Your CI      vibeview     vibeview    Exit code
 or cloud     upload-app   run-suites  + run URLs
 build

1. Build your app, in your CI or with a cloud build
2. Upload the build to VibeView, and keep its build id
3. Run your tagged groups (or one AI test) against that build, and wait for the result
4. Read the results: the exit code, and a link to every run’s page

Step-by-Step Walkthrough

This walkthrough uses a concrete example: you changed an iOS app and want to verify it on a simulator before merging.

Step 1: Build your app

Build an iOS simulator build (.ipa device archives are not supported) or an Android .apk. For a React Native app, build the Release configuration, so the JavaScript bundle is inside the app: a Debug build waits for a Metro server that CI doesn’t have.

iOS (Xcode, on a Mac):

xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release \
  -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath build CODE_SIGNING_ALLOWED=NO

Android (Gradle):

./gradlew assembleRelease

An Android build must include the x86_64 ABI (see Preparing your build).

No Mac? vibeview build --cloud --platform ios --json builds the iOS app in the cloud from your vibeview.json and adds it to your app’s build history, so you can skip Step 2: take the build id from the app_build_id field of the build_finished event (see Cloud Builds).

Step 2: Upload the build

vibeview upload-app build/Build/Products/Release-iphonesimulator/MyApp.app --output json

The CLI accepts the .app directory or a zip of it for iOS, and an .apk for Android. Output:

{
  "app_id": "a1b2c3d4",
  "name": "MyApp",
  "package_name": "com.example.myapp",
  "platform": "ios",
  "is_new": false,
  "build_id": 4812,
  "version": "1.4.0",
  "build_number": "57",
  "deduplicated": false,
  "note": null,
  "url": "https://vibeview.io/apps/a1b2c3d4",
  "warnings": []
}

VibeView detects the platform and bundle ID from the build. If an app with the same bundle ID already exists, the build is added to it instead of creating a new app. Keep build_id: the next step pins the run to it.

Step 3: Run your tests against that build

Tagged groups (recommended). Record or write your test cases in VibeView, put them in groups, and tag the groups you want in CI:

vibeview run-suites --tag smoke --platform ios --build 4812 \
  --commit-sha "$(git rev-parse HEAD)" --output json

This runs every smoke group of the iOS app against build 4812, in hybrid mode (Smart in the dashboard; replay is No AI and ai is AI only): recorded steps replay, and the AI agent (beta) handles the steps that have no recording. To retry a failed test once, add --retry.

An AI test (beta) from plain-English steps. Useful when an AI coding agent writes the test along with the change:

TEST_ID=$(vibeview create-test "Login Flow" \
  --app a1b2c3d4 \
  --steps '["Launch the app", "Tap Sign In", "Enter test credentials", "Verify home screen loads"]' \
  --context "Test account: testuser@example.com / password123" \
  --if-exists update \
  --output json | jq -r .test_id)

vibeview run-test "$TEST_ID" --build 4812 --commit-sha "$(git rev-parse HEAD)" --output json

Steps are natural language: write them as you would instruct a human tester. --context gives the AI agent background it needs that isn’t a step (credentials, expected app state, what changed). --if-exists update replaces the steps of an existing test of this app with the same name that is in no group; without it, create-test reuses an identical test and refuses a different one. Every run of an AI test is billed to usage credit, unless you use your own AI provider key.

Either way, the CLI handles the whole run: it waits for a free device (queueing if needed), runs the tests, and prints the result. --build makes sure the run tests the build you just made rather than the app’s latest upload. With the GitHub integration connected, --commit-sha posts a commit status per group (or for the test).

Step 4: Read the results

The CLI exit code tells you the outcome:

With --output json, the result is one JSON document on stdout, with a link to each group run and each test case run (url), and the usage credit it billed (cost_micro, in millionths of a dollar). A run’s page in VibeView has a step-by-step timeline with screenshots and the AI agent’s reasoning. --output junit writes a JUnit XML report instead.

Use the exit code to gate your pipeline:

vibeview run-suites --tag smoke --platform ios --build "$BUILD_ID" --commit-sha "$COMMIT_SHA" || exit 1

Quick Path: GitHub Actions

For GitHub repositories, use the VibeView workflow template. It builds your iOS app in the cloud and your Android app in your workflow, runs your tagged groups against those builds, and keeps one comment per platform on the pull request. See CI Testing for the setup, and GitHub Checks for commit statuses and required checks.

Quick Path: Any CI

For GitLab CI, CircleCI, Jenkins and other systems, run the same commands in your pipeline:

npm install -g vibeview

# Upload the build your pipeline made, and keep its id.
BUILD_ID=$(vibeview upload-app ./android/app/build/outputs/apk/release/app-release.apk \
  --output json | jq -er .build_id)

# Run the tagged suites against it.
vibeview run-suites --tag smoke --platform android --build "$BUILD_ID" \
  --commit-sha "$(git rev-parse HEAD)" --output junit > vibeview-results.xml

See CI Testing: Other CI systems for the cloud-build variant.

Environment Variables

In GitHub Actions, store the token as a repository secret (Settings > Secrets and variables > Actions) and pass it to the steps that call the CLI through env:.

Requirements Checklist: Integrating VibeView into an AI Agent

If you are building an AI agent that needs to verify code changes on a live mobile simulator or emulator, implement the following requirements. Each requirement is a discrete capability the agent needs.

Setup (one-time)

• REQ-SETUP-01: Agent has access to a VibeView API token stored as a secret or environment variable
• REQ-SETUP-02: Agent can install the VibeView CLI (npm install -g vibeview)
• REQ-SETUP-03: Agent can build the target app (has a build toolchain configured), or uses vibeview build --cloud

Test Specification

• REQ-SPEC-01: Agent generates a .vibeview/test-spec.json file from the ticket or task context (see CI Testing)
• REQ-SPEC-02: Test steps are written in natural language describing user-visible actions
• REQ-SPEC-03: Context field includes relevant background (test credentials, app state, what changed)
• REQ-SPEC-04: The upload-app argument points to the freshly built artifact

Execution

• REQ-EXEC-01: Agent uploads the app build via vibeview upload-app and keeps the returned build_id
• REQ-EXEC-02: Agent creates or updates the test case via vibeview create-test --if-exists update with steps from the spec
• REQ-EXEC-03: Agent runs the test via vibeview run-test --build <build_id> and waits for completion
• REQ-EXEC-04: Agent passes --commit-sha to associate results with the code change (and post a commit status, with the GitHub integration connected)

Result Handling

• REQ-RESULT-01: Agent checks exit code (0 = pass, 1 = fail, 2 = error)
• REQ-RESULT-02: On failure, agent extracts the run URL from JSON output for debugging
• REQ-RESULT-03: Agent can re-run the test after making fixes (update the test or re-run it)
• REQ-RESULT-04: Agent reports results back to its orchestrator (Jira comment, PR status, etc.)

Troubleshooting

“Authentication failed”: check that VIBEVIEW_API_TOKEN is set and was copied in full (tokens are shown only once at creation). A token created with an expiry stops working when it expires: the error says so, and the fix is a new token. If in doubt, generate a new token at Settings > API token.

“App upload failed”: check that the path exists and is a simulator .app (or a zip of it) or an .apk, under 500 MB. .ipa device archives are rejected.

No suites match tags: no group with that tag exists on that platform. Check with vibeview list-suites --tag <tag>, and that the groups’ platform (or their app’s) matches --platform.

build_id ... is not valid for suites: a tagged group belongs to a different app than the build. A run pinned with --build needs every matched group to belong to that build’s app.

“Test timed out”: --timeout (default 1800 seconds, per group for run-suites) covers waiting for a free device as well as the run. If runs often wait, check the device queue in the VibeView dashboard.

“No devices available”: the CLI queues the run and waits for a free device, within --timeout. If the wait persists, check the VibeView dashboard for device status and the current queue.

Next Steps

• CLI Reference: every CLI command
• CI Testing: the GitHub Actions workflow template, test-spec.json, and run results
• GitHub Checks: commit statuses and required checks
• API Reference: direct API access for custom integrations