--- description: Calabash Testing Tutorial - Calabash is an open source Acceptance testing framework that allows you to write and execute tests for iOS and Android Apps. title: Calabash Android Testing Tool Tutorial image: https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png --- [Skip to content](#main) **⚡ Smart Summary** Calabash is an open-source acceptance testing framework that drives real user interface actions on Android and iOS applications, using plain-English Cucumber scenarios backed by Ruby step definitions and a device-side test server. * 🔸 **Definition:** Calabash automates taps, text entry and assertions against native and hybrid mobile applications on real devices and emulators. * ☑️ **Language stack:** Scenarios are written in Gherkin feature files, and the matching methods live in Ruby files inside step\_definitions. * ✅ **BDD foundation:** Behavior Driven Development lets business owners, developers and testers agree on behaviour before any script exists. * 🧪 **Setup order:** Java JDK, then Ruby, then Android Studio, then the calabash-android gem, verified with a version command. * 🛠️ **Execution flow:** Resign the APK, build the test server, attach a device, query locators, then run the feature files. * 📊 **Current status:** Calabash is archived and unmaintained, so new projects generally choose Appium, Espresso or XCUITest instead. [ Read More ](javascript:void%280%29;) ![Calabash testing tool tutorial for Android showing Cucumber feature files driving a mobile application](https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png) ## What is Calabash? Calabash is an open-source Acceptance [Testing](https://www.guru99.com/software-testing.html) framework that allows you to write and execute tests for iOS and Android Apps. It is an Automated User Interface Framework that allows tests to be written in Ruby using [Cucumber](https://www.guru99.com/cucumber-basics.html). Calabash works by enabling automatic UI interactions within a Mobile application such as pressing buttons, inputting text, validating responses, etc. It can be configured to run on different Android and iOS devices, which provides real-time feedback and validations. ⚠️ **Version note:** Microsoft ended its contributions to Calabash after the final iOS 11 and Android 8 releases, and the [calabash-android repository](https://github.com/calabash/calabash-android) now describes itself as a project looking for a maintainer. The walkthrough below is preserved as written, and the modern replacements are covered in the last section. ## Why Calabash Automation? Before installing anything, it helps to weigh what the framework gives back against what it costs to maintain. | Advantages | Disadvantages | | ------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | It helps to increase throughput/ productivity. | Proficiency is required to write the automation test scripts. | | Improved quality or increased predictability of quality | Debugging the test script is a major issue. | | Improved robustness (consistency) of processes or products. | Test maintenance is costly in case of playback methods. | | Increased consistency of output and reduce labor costs and expenses | Maintenance of test data files is difficult if the test script tests more screens | ## Calabash and BDD * Calabash is **Behavior Driven Development (BDD)**. It is same as [Test Driven Development (TDD)](https://www.guru99.com/test-driven-development.html), but instead of creating tests to describe the shape of APIs, application behavior is specified. * BDD is a process in which multiple stakeholders weigh in to create a common understanding of what has to be built. * BDD is helpful in building the right software and designing from the perspective of the business owner. The diagram below shows how a Calabash suite is layered, from the business-readable feature file at the top down to the device interaction at the bottom. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut1.png) ## How to install Calabash Calabash on Windows needs four prerequisites installed in order. Complete each part fully before starting the next one, because the calabash-android gem checks for Ruby and the Android SDK during installation. Part I) Install [Java](https://www.guru99.com/java-tutorial.html) JDK – Refer to this guide – [/install-java.html](https://www.guru99.com/install-java.html) Part II) Download and install Ruby. Step 1) Download Ruby from the URL [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut2.png) Step 2) Open the exe, follow the instructions on the screen. Once install is complete you will see the following screen. Click Finish. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut3.png) Start Command Prompt with Ruby on Windows 10 & type below Command. ruby -v The console prints the installed interpreter version, as shown below. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut4.png) Part III) Download and install Android Step 1) Download Android Studio at [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut5.png) Step 2) Open the exe, follow the on-screen instructions and complete installation. Click the finish button once done [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut6.png) Part IV) Install Calabash Android Step 1) In the console type gem install calabash-android. The install will start and will take some time to complete [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut7.png) Step 2) Once installation is done Type calabash-android version [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut8.png) ### RELATED ARTICLES * [iOS App Testing Tutorial ](https://www.guru99.com/getting-started-with-ios-testing.html "iOS App Testing Tutorial") * [Appium Tutorial for Beginners ](https://www.guru99.com/introduction-to-appium.html "Appium Tutorial for Beginners") * [7 BEST Mobile App Testing Tools (2026) ](https://www.guru99.com/mobile-testing-tools.html "7 BEST Mobile App Testing Tools (2026)") * [Live Appium Testing Project ](https://www.guru99.com/live-mobile-testing-project.html "Live Appium Testing Project") ## Working with Calabash With the gem installed, the next task is to locate the framework folder and understand the skeleton it ships with. Open the “calabash-android-0.9.0” folder. It resides at path C:\\Ruby23\\lib\\ruby\\gems\\2.3.0\\gems\\calabash-android-0.9.0\. The folder names will change in synch with the ruby/ calabash version you install on your machine. Open the feature skeleton folder. Look out for this basic framework. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut9.png) * The \*.feature file contains scenarios that we are going to automate. * The method used by the feature file is written in \*.rb file inside “step\_definitions” folder. * Common methods, environment setup, app installation and hooks should be placed inside “support” folder. ### Resign & Build the app * Calabash-android resign \*.apk * Calabash-android build \*.apk Resigning replaces the developer signature with a debug key so the test server may instrument the application, and the build step produces that test server, as the console output below shows. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut10.gif) ### Attach the device to the system /Open the emulator Check device attached. Type command adb devices Attached devices list should be displayed. If the device is missing, the USB debugging and pairing steps in the [ADB connect guide](https://www.guru99.com/adb-connect.html) resolve most cases. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut11.gif) ### How to Find the Element Locator * Open the console. Type the Command. calabash-android console "APK Path" start_test_server_in_background * Above command launch the app on the device. To find the element locator use following command. query "*" This will display all the element locators on the current screen. Testers who prefer a visual inspector can cross-check the same hierarchy with [uiautomatorviewer](https://www.guru99.com/uiautomatorviewer-tutorial.html). [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut12.gif) ## Calabash Project Structure and Predefined Steps Rather than copying the gem folder by hand, the framework can generate a working project for you. Running the generator inside your project directory creates the standard Cucumber layout that every Calabash suite expects. calabash-android gen The generated tree separates the three concerns of a BDD suite: * **features/** — the Gherkin scenarios, one _.feature_ file per user journey. * **features/step\_definitions/** — the Ruby methods that match each Gherkin line, including the bundled calabash\_steps.rb. * **features/support/** — environment configuration and the hooks that install, launch and shut down the application around every scenario. The bundled calabash\_steps.rb matters more than it first appears. It ships a large set of ready-made English steps, so a first scenario can press buttons, enter text and assert on visible strings before a single custom method is written. Custom steps are only needed once a journey outgrows those canned phrases. Two project-level settings are worth knowing early. Screenshots land in the current working directory by default, and the SCREENSHOT\_PATH environment variable redirects them elsewhere, which keeps build artefacts tidy on a shared machine. Interacting with system dialogs or another application requires the UIAutomator2 backend, started with start\_test\_server\_in\_background(with\_uiautomator: true). ## Creating New Scripts Open the feature file and following lines [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut13.png) Feature: Login feature Scenario: As a valid user I can log into my app When I press "Login" And I enter my username And I enter my password Then I see "Welcome to coolest app ever" Open the Step Definition file & Define the method into \*.rb file. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut14.png) Given /^I am on the login windows$/ do wait_for(:timeout =>100) { element_exists("* id:'loginInput;")} check_element_exists("* id:'loginInput;") end ### Execute the test project To execute the test project, use command below calabash-android run "APK Path" "feature file Path" --tags "tag name" Cucumber prints each step as it executes, and a passing run ends with the scenario and step totals shown here. [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut15.gif) [](https://www.guru99.com/images/2-2017/051917%5F1209%5FCalabashTut16.gif) ## Common Calabash Errors and How to Fix Them Most first-run failures come from the packaging and permission rules the test server depends on, not from the scenario itself. The table below maps the symptoms reported most often to their documented cause. | Symptom | Likely cause and fix | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | The application crashes the instant a test starts | The APK is missing android.permission.INTERNET, which the test server needs to accept commands. Declare the permission in AndroidManifest.xml and rebuild. | | Buttons and text refuse to respond to taps | No targetSdkVersion is declared. Add a uses-sdk entry naming the SDK level the application was built against. | | The test server cannot connect to the application | The APK was not resigned with the debug key. Run the resign command, then build again before running. | | No devices are listed at run time | USB debugging is off or the driver is missing. Confirm the serial number appears in the adb devices output first. | | Steps fail with an undefined step error | The Gherkin wording does not match any regular expression in step\_definitions. Copy the suggested snippet Cucumber prints and implement it. | Two manifest entries fix the first two rows. Add them before resigning the APK. Timeout failures are usually environmental rather than functional. A slow emulator, a cold application start or a background sync can all push a screen past the wait\_for window, so raise the timeout before rewriting a step that was actually correct. ## Is Calabash Still Maintained? Alternatives for Modern Mobile Testing Calabash is no longer actively developed. Microsoft stopped contributing after supporting the final iOS 11 and Android 8 releases, and the project is now an archived open-source code base without a maintainer. Existing suites still run on older devices, but new work should start on a supported framework. | Framework | Platform | Best suited to | | ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Appium | Android and iOS | Cross-platform suites in Java, Python, Ruby or JavaScript, and the closest replacement for a Calabash team. | | Espresso | Android only | Fast in-process tests written in Kotlin or Java by the application developers themselves. | | XCUITest | iOS only | Native Xcode suites, the supported successor to the retired [UIAutomation framework](https://www.guru99.com/ios-test-program-uiautomation-framework.html). | | Maestro and Detox | Android and iOS | Newer open-source projects aimed at flake resistance and React Native applications. | The BDD habit itself transfers cleanly. Gherkin feature files stay exactly as they are, and only the step definition bodies change, because Cucumber sits above the driver rather than inside it. Teams migrating usually keep the feature files, rewrite the Ruby steps against Appium, and reuse the same [mobile testing](https://www.guru99.com/mobile-testing.html) device matrix and [automation testing](https://www.guru99.com/automation-testing.html) pipeline they already run. ## FAQs 🍏 Does Calabash support iOS apps as well as Android? Yes. A separate calabash-ios gem drove iOS applications through the same Ruby and Cucumber layer. It shares the deprecation status of the Android gem, so current iOS work is better served by XCUITest or Appium. 🤖 How is AI changing mobile UI test automation? Machine learning models now repair broken locators automatically, flag flaky scenarios by comparing run histories, and cluster crash reports so the most damaging defects surface first. The judgement about what to assert still belongs to the tester. 🧑‍💻 Can GitHub Copilot help write Calabash step definitions? Copilot drafts the repetitive parts well, such as a wait\_for block wrapping an element query. It cannot know your application’s element identifiers, so treat every generated step as a draft to verify against a live query result. 🥒 What is the difference between Calabash and Cucumber? [Cucumber](https://www.guru99.com/cucumber-basics.html) is the generic BDD runner that reads Gherkin and calls Ruby methods. Calabash is the mobile automation library those methods call. Cucumber decides what runs; Calabash performs the tap, the text entry and the assertion. 📸 Where does Calabash store screenshots from a test run? Screenshots are written to the current working directory by default, named sequentially per run. Setting the SCREENSHOT\_PATH environment variable before the run redirects them to a chosen folder, which keeps continuous integration artefacts separate from source code. 🧾 Do I need my application’s source code to run Calabash tests? No. Calabash instruments a compiled APK, which is why the resign step exists. Source access helps you add stable element identifiers, but the framework itself only needs a build it is allowed to resign and instrument. 🖥️ Can Calabash tests run inside a CI pipeline? Yes. Because execution is a single command-line call, any build server can invoke it after the APK is produced. A [Jenkins](https://www.guru99.com/jenkins-tutorial.html) job typically resigns the APK, starts an emulator, runs the tagged features and archives the reports. 🔄 How do I migrate a Calabash suite to Appium? Keep the Gherkin feature files unchanged and rewrite only the step definition bodies against the Appium client. Element queries become locator strategies, and the hooks that installed the application become desired capabilities in the driver setup. #### Summarize this post with: ChatGPT Perplexity Grok Google AI **Stay Updated on AI** **Get Weekly AI Skills, Trends, Actionable Advice.** ##### Sign up for the newsletter Subscribe for Free You have successfully subscribed. Please check your inbox. ![AI-Newsletter]() Chosen by over **350,000+** professionals [Scroll to top ](#wrapper)Scroll to top × Toggle Menu Close Search for: Search ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://www.guru99.com/#organization","name":"Guru99","sameAs":["https://www.facebook.com/Guru99Official","https://twitter.com/guru99com"],"logo":{"@type":"ImageObject","@id":"https://www.guru99.com/#logo","url":"https://www.guru99.com/images/guru99-logo-v1-150x59.png","contentUrl":"https://www.guru99.com/images/guru99-logo-v1-150x59.png","caption":"Guru99","inLanguage":"en-US"}},{"@type":"WebSite","@id":"https://www.guru99.com/#website","url":"https://www.guru99.com","name":"Guru99","publisher":{"@id":"https://www.guru99.com/#organization"},"inLanguage":"en-US"},{"@type":"ImageObject","@id":"https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png","url":"https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png","width":"700","height":"250","caption":"Calabash Android Testing Tool Tutorial","inLanguage":"en-US"},{"@type":"BreadcrumbList","@id":"https://www.guru99.com/calabash-android-ios-testing.html#breadcrumb","itemListElement":[{"@type":"ListItem","position":"1","item":{"@id":"https://www.guru99.com","name":"Home"}},{"@type":"ListItem","position":"2","item":{"@id":"https://www.guru99.com/mobile-testing","name":"Mobile Apps Testing"}},{"@type":"ListItem","position":"3","item":{"@id":"https://www.guru99.com/calabash-android-ios-testing.html","name":"Calabash Android Testing Tool Tutorial"}}]},{"@type":"WebPage","@id":"https://www.guru99.com/calabash-android-ios-testing.html#webpage","url":"https://www.guru99.com/calabash-android-ios-testing.html","name":"Calabash Android Testing Tool Tutorial","dateModified":"2026-07-30T11:03:49+05:30","isPartOf":{"@id":"https://www.guru99.com/#website"},"primaryImageOfPage":{"@id":"https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png"},"inLanguage":"en-US","breadcrumb":{"@id":"https://www.guru99.com/calabash-android-ios-testing.html#breadcrumb"}},{"@type":"Person","@id":"https://www.guru99.com/author/thomas","name":"Thomas Hamilton","description":"I am Thomas Hamilton, a seasoned professional in software testing, specializing in crafting comprehensive guides to help you master your software testing skills.","url":"https://www.guru99.com/author/thomas","image":{"@type":"ImageObject","@id":"https://www.guru99.com/images/thomas-hamilton-author-v2-120x120.png","url":"https://www.guru99.com/images/thomas-hamilton-author-v2-120x120.png","caption":"Thomas Hamilton","inLanguage":"en-US"},"worksFor":{"@id":"https://www.guru99.com/#organization"}},{"articleSection":"Mobile Apps Testing","headline":"Calabash Android Testing Tool Tutorial","description":"Calabash Testing Tutorial - Calabash is an open source Acceptance testing framework that allows you to write and execute tests for iOS and Android Apps.","keywords":"mobile","speakable":{"@type":"SpeakableSpecification","cssSelector":[".entry-title",".summary"]},"@type":"Article","author":{"@id":"https://www.guru99.com/author/thomas","name":"Thomas Hamilton"},"dateModified":"2026-07-30T11:03:49+05:30","image":{"@id":"https://www.guru99.com/images/calabash-android-testing-tool-tutorial.png"},"copyrightYear":"2026","name":"Calabash Android Testing Tool Tutorial","subjectOf":[{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Does Calabash support iOS apps as well as Android?","acceptedAnswer":{"@type":"Answer","text":"Yes. A separate calabash-ios gem drove iOS applications through the same Ruby and Cucumber layer. It shares the deprecation status of the Android gem, so current iOS work is better served by XCUITest or Appium."}},{"@type":"Question","name":"How is AI changing mobile UI test automation?","acceptedAnswer":{"@type":"Answer","text":"Machine learning models now repair broken locators automatically, flag flaky scenarios by comparing run histories, and cluster crash reports so the most damaging defects surface first. The judgement about what to assert still belongs to the tester."}},{"@type":"Question","name":"Can GitHub Copilot help write Calabash step definitions?","acceptedAnswer":{"@type":"Answer","text":"Copilot drafts the repetitive parts well, such as a wait_for block wrapping an element query. It cannot know your application's element identifiers, so treat every generated step as a draft to verify against a live query result."}},{"@type":"Question","name":"What is the difference between Calabash and Cucumber?","acceptedAnswer":{"@type":"Answer","text":"Cucumber is the generic BDD runner that reads Gherkin and calls Ruby methods. Calabash is the mobile automation library those methods call. Cucumber decides what runs; Calabash performs the tap, the text entry and the assertion."}},{"@type":"Question","name":"Where does Calabash store screenshots from a test run?","acceptedAnswer":{"@type":"Answer","text":"Screenshots are written to the current working directory by default, named sequentially per run. Setting the SCREENSHOT_PATH environment variable before the run redirects them to a chosen folder, which keeps continuous integration artefacts separate from source code."}},{"@type":"Question","name":"Do I need my application's source code to run Calabash tests?","acceptedAnswer":{"@type":"Answer","text":"No. Calabash instruments a compiled APK, which is why the resign step exists. Source access helps you add stable element identifiers, but the framework itself only needs a build it is allowed to resign and instrument."}},{"@type":"Question","name":"Can Calabash tests run inside a CI pipeline?","acceptedAnswer":{"@type":"Answer","text":"Yes. Because execution is a single command-line call, any build server can invoke it after the APK is produced. A Jenkins job typically resigns the APK, starts an emulator, runs the tagged features and archives the reports."}},{"@type":"Question","name":"How do I migrate a Calabash suite to Appium?","acceptedAnswer":{"@type":"Answer","text":"Keep the Gherkin feature files unchanged and rewrite only the step definition bodies against the Appium client. Element queries become locator strategies, and the hooks that installed the application become desired capabilities in the driver setup."}}]}],"@id":"https://www.guru99.com/calabash-android-ios-testing.html#schema-1155420","isPartOf":{"@id":"https://www.guru99.com/calabash-android-ios-testing.html#webpage"},"publisher":{"@id":"https://www.guru99.com/#organization"},"inLanguage":"en-US","mainEntityOfPage":{"@id":"https://www.guru99.com/calabash-android-ios-testing.html#webpage"}}]} ```