CI/CD Integration Guide

VibeView lets you run AI-powered mobile tests on real iOS simulators and Android emulators as part of your CI/CD pipeline. This guide walks through the full pipeline from building your app to analyzing test results. It is the starting point for integration — see CLI Reference, CI Testing, and GitHub Checks for detailed reference documentation.

Prerequisites

Before starting, make sure you have:

• A VibeView account with an API token (generate one at Settings > API Tokens)
• A built app artifact (.app simulator build for iOS, or .apk for Android)
• Node.js 20 or later
• The VibeView CLI installed:

npm install -g @scriptx-com/vibeview-cli

Pipeline Overview

Every CI/CD integration follows the same five steps:

Build App  -->  Upload  -->  Create Test  -->  Run  -->  Results
   |              |              |              |           |
 Your CI      vibeview       vibeview       vibeview    Exit code
 toolchain    upload-app     create-test    run-test    + run URL

1. Build your app — Compile your iOS or Android app in CI
2. Upload the build — Push the artifact to VibeView
3. Create a test case — Define what to test in natural language
4. Run the test — Execute on a real simulator, wait for results
5. Analyze results — Check pass/fail status and review the run detail page

Step-by-Step Walkthrough

This walkthrough uses a concrete example: you made a code change to an iOS app and want to verify it works on a simulator.

Step 1: Build your app

Build your app artifact in CI. This is specific to your project and build toolchain.

iOS (Xcode):

xcodebuild -scheme MyApp -sdk iphonesimulator -derivedDataPath build

Android (Gradle):

./gradlew assembleDebug

The output is a .app (iOS simulator build) or .apk file that VibeView uploads and installs on a simulator. Note: .ipa device archives are not supported — iOS simulators need simulator .app builds.

Step 2: Upload the build

vibeview upload-app ./build/MyApp.app --output json

Output:

{
  "app_id": "a1b2c3d4",
  "name": "MyApp",
  "platform": "ios"
}

VibeView auto-detects the bundle ID. If an app with the same bundle ID already exists, it updates the existing entry instead of creating a duplicate.

Step 3: Create a test case

vibeview create-test \
  --app a1b2c3d4 \
  --steps '["Launch the app", "Tap Sign In", "Enter test credentials", "Verify home screen loads"]' \
  --context "Test account: testuser@example.com / password123" \
  --test-name "Login Flow" \
  --output json

Output:

{
  "test_id": "t5e6f7g8"
}

Steps are natural language — write them as you would instruct a human tester. The AI agent interprets each step, interacts with the app UI, and reports pass/fail per step.

Platform is auto-detected from the uploaded build (.app → iOS, .apk → Android). You only need --platform on create-test if you are passing a bundle ID or package name to --app instead of the app_id returned from upload-app.

The --context flag provides background information the AI agent needs but that is not a test step (credentials, expected app state, what changed in this build).

Step 4: Run the test

vibeview run-test t5e6f7g8 \
  --commit-sha $(git rev-parse HEAD) \
  --output json

Output:

{
  "run_id": "r9h0i1j2",
  "status": "passed",
  "url": "https://vibeview.io/tests/runs/r9h0i1j2",
  "duration_ms": 18450
}

The CLI handles the full lifecycle: waits for an available simulator (device queue), runs the test, and returns results. The --commit-sha flag enables GitHub Checks — the test result appears as a commit status on your pull request.

Step 5: Analyze results

The CLI exit code tells you the outcome:

The url field in JSON output links to the full run detail page in VibeView, which includes a step-by-step timeline with screenshots and a conversation log showing the AI agent’s reasoning.

Use the exit code in your CI pipeline to gate deployments:

vibeview run-test $TEST_ID --commit-sha $COMMIT_SHA || exit 1

Quick Path: GitHub Workflow Template

For GitHub repositories, skip manual CLI commands. The vibeview-test workflow template handles everything automatically.

1. Create .vibeview/test-spec.json in your repository root:

{
  "version": 1,
  "test_name": "Login Flow",
  "steps": [
    "Launch the app",
    "Tap Sign In",
    "Enter test credentials",
    "Verify home screen loads"
  ],
  "context": "Test account: testuser@example.com / password123"
}

The build artifact path is configured in the workflow (via the APP_PATH env var in the VibeView workflow template), and platform is auto-detected from the binary when uploading.

2. Add the workflow template:

Copy templates/vibeview-test.yml (provided by VibeView) to .github/workflows/vibeview-test.yml in your repository, then:

• Set the APP_PATH env var in the workflow to your build output (e.g., ./build/Build/Products/Debug-iphonesimulator/MyApp.app), and add your build step where the template indicates.
• Add the VIBEVIEW_API_TOKEN and VIBEVIEW_NPM_TOKEN secrets (Settings > Secrets and variables > Actions).

The workflow reads test-spec.json, uploads the app, creates a test, runs it with the PR commit SHA, and posts a detailed comment on the pull request with pass/fail status and step results. See CI Testing for the full test-spec.json schema and workflow-template setup, and GitHub Checks for status check configuration.

Quick Path: test-spec.json for Any CI

For non-GitHub CI systems (GitLab CI, CircleCI, Jenkins), use test-spec.json with the CLI directly.

1. Create .vibeview/test-spec.json (same schema as above).

2. Run this script in your CI pipeline:

# Parse the spec
STEPS=$(jq -c .steps .vibeview/test-spec.json)
CONTEXT=$(jq -r '.context // ""' .vibeview/test-spec.json)
TEST_NAME=$(jq -r '.test_name // "CI Test"' .vibeview/test-spec.json)

# Upload the app (APP_PATH points to your build output; platform is auto-detected)
APP_PATH="./build/MyApp.app"
APP_ID=$(vibeview upload-app "$APP_PATH" --output json | jq -r .app_id)

# Create the test
TEST_ID=$(vibeview create-test \
  --app "$APP_ID" \
  --steps "$STEPS" \
  --context "$CONTEXT" \
  --test-name "$TEST_NAME" \
  --output json | jq -r .test_id)

# Run the test
vibeview run-test "$TEST_ID" \
  --commit-sha $(git rev-parse HEAD) \
  --output json

This is the same pipeline the workflow template runs internally. See CI Testing for the full test-spec.json schema.

Environment Variables

In GitHub Actions, set these as repository secrets (Settings > Secrets and variables > Actions). The workflow template reads the VIBEVIEW_API_TOKEN repository secret.

Requirements Checklist: Integrating VibeView into an AI Agent

If you are building an AI agent that needs to verify code changes on a real mobile simulator, 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 @scriptx-com/vibeview-cli)
• REQ-SETUP-03: Agent can build the target app (has build toolchain configured)

Test Specification

• REQ-SPEC-01: Agent generates a .vibeview/test-spec.json file from the ticket or task context
• 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 APP_PATH env var (or the CLI’s upload-app argument) points to the freshly built artifact

Execution

• REQ-EXEC-01: Agent uploads the app build via vibeview upload-app
• REQ-EXEC-02: Agent creates a test case via vibeview create-test with steps from the spec
• REQ-EXEC-03: Agent runs the test via vibeview run-test and waits for completion
• REQ-EXEC-04: Agent passes --commit-sha to associate results with the code change

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 (create new test or re-run existing)
• 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 and do not expire). If in doubt, generate a new token at Settings > API Tokens.

“App upload failed” — Verify the file path exists and the file is a valid simulator .app or .apk under 500 MB (.ipa device archives are rejected).

“Test timed out” — Increase --timeout (default is 300 seconds). Check if a device is available in the VibeView dashboard.

“No devices available” — The CLI auto-queues and waits for an available simulator. If the wait is persistent, check the VibeView dashboard for device status and current queue length.

“test-spec.json validation failed” — Ensure version is 1, steps is present and contains at least one entry, and the workflow’s APP_PATH env var points at an existing build artifact.

Next Steps

• CLI Reference — Full command reference for all CLI commands
• CI Testing — test-spec.json schema and advanced CI patterns
• GitHub Checks — GitHub integration and commit status checks
• API Reference — Direct API access for custom integrations