qawolf plugin

Getting Started

This project is a fastlane plugin. To get started with fastlane-plugin-qawolf, add it to your project by running:

# Add this to your Gemfile
gem "fastlane-plugin-qawolf", git: "https://github.com/qawolf/fastlane-plugin-qawolf", tag: "0.2.0"

About qawolf

Fastlane plugin for QA Wolf integration.

Uploads build artifacts (IPA, APK, or AAB) to QA Wolf storage for automated testing. Optionally triggers a test run on QA Wolf.

Caution

To ensure QA Wolf tests target the correct app build and help debugging issues, we require uploaded filenames to be unique in some way. The example below uses the git commit hash, but you can use another unique identifier such as the app version number if you wish.

Important

Testing iOS apps (IPA) on QA Wolf is not yet available.

Example

Check out the example Fastfile to see how to use this plugin. Try it by cloning the repo, running fastlane install_plugins and bundle exec fastlane test.

lane :build do
    # The uploaded filename must be unique for your team on the QA Wolf platform.
    # One way to achieve that is to rely on the git commit hash.
    # Feel free to use a different mechanism if desired (e.g. app version).
    # See https://docs.fastlane.tools/actions/#source-control for other source control actions
    ensure_git_status_clean
    commit = last_git_commit

    # Build your app
    # Ensure the APK/AAB file has been created. Your use case may vary.
    # Check Fastlane's docs for alternative build methods.
    gradle(
        task: "assemble",
        build_type: "Release",
    )

    # Upload the artifact to QA Wolf
    upload_to_qawolf(
        # Must be set or available as env var QAWOLF_API_KEY
        qawolf_api_key: "qawolf_...",

        # You can omit this if your gradle build outputs the file with a unique filename.
        # If not, you'll want to do something like the following.
        # Make sure you use the right file extension!
        filename: "app_#{commit[:abbreviated_commit_hash]}.apk"

        # Only set this if you have not built the artifact in the same lane,
        # e.g. via gradle or similar, check official Fastlane docs for details.
        file_path: "./build/app-bundle.apk",
    )

    # Trigger a test run on QA Wolf
    # Optional, only use when deployment triggers are enabled in QA Wolf
    notify_deploy_qawolf(
        # Must be set or available as env var QAWOLF_API_KEY
        qawolf_api_key: "qawolf_...",

        # These fields are dependent on how triggers are setup within QA Wolf.
        # Reach out to support for help. All fields are optional.
        branch: nil,
        commit_url: nil,
        deduplication_key: nil,
        deployment_type: nil,
        deployment_url: nil,
        hosting_service: nil,
        sha: nil,
        variables: nil,

        # Only set this if your lane does not include `upload_to_qawolf`
        run_input_path: nil,
    )
end

Run tests for this plugin

To run both the tests, and code style validation, run

bundle exec rake

To automatically fix many of the styling issues, use

bundle exec rubocop -A

Issues and Feedback

For any other issues and feedback about this plugin, please submit it to this repository.

Troubleshooting

If you have trouble using plugins, check out the Plugins Troubleshooting guide.

Using fastlane Plugins

For more information about how the fastlane plugin system works, check out the Plugins documentation.

About fastlane

fastlane is the easiest way to automate beta deployments and releases for your iOS and Android apps. To learn more, check out fastlane.tools.

Local development

The instructions below are for maintainers of this plugin.

Setup

1. Clone the repository and cd into the directory

   git clone [email protected]:qawolf/fastlane-plugin-qawolf.git
   cd fastlane-plugin-qawolf

2. Install a modern version of Ruby. By default macOS ships with v2.x. I recommend using asdf to install the version defined in .tool-versions .

   1. Install asdf

      # requires that git, curl, and coreutils are installed on macOS
      git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1
      # ensure asdf is loaded into PATH (also add this to your .zshrc file)
      . "$HOME/.asdf/asdf.sh”

   2. Install the asdf Ruby plugin

      asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git

   3. Install the specified version of Ruby

      # must be run inside the plugin root folder
      asdf install
      # confirm the ruby version
      ruby --version # <- should print a version matching .tool-versions

3. Install dependencies with the bundler CLI

   bundle install # may need to run `gem install bundler` first

4. Confirm unit tests are passing (this suite will mock API calls and the file system)

   bundle exec rake

Use the plugin in an Android project

1. Create a new or use an existing Android project.

2. Open the directory of the project in a terminal.

3. Setup a Gemfile and install fastlane

   # create Gemfile
   cat <<EOF >> ./Gemfile
   source "https://rubygems.org"
   
   gem "fastlane"
   EOF
   
   # install deps
   bundle update

4. Setup fastlane config

   bundle exec fastlane init

5. While the Android setup guide can be useful, we only care about uploading the APK to our QA Wolf platform. So the next step is to build and install our plugin. Make sure you update the path to the plugin!

   # in the plugin root directory
   gem build fastlane-plugin-qawolf.gemspec # <- outputs a *.gem file
   
   # in the Android project root directory
   echo 'gem "fastlane-plugin-qawolf", path: "~/path/to/fastlane-plugin-qawolf"' >> Gemfile
   bundle install

6. Time to update the ./fastlane/Fastlane file in the Android project.

   default_platform(:android)
   
   platform :android do
     desc "Upload to QA Wolf"
     lane :upload do
       # builds an unsigned APK by default
       # in a real setup you will need to create a signed APK (or AAB) to use it in QA Wolf
       gradle(task: "clean assembleRelease")
   
       # relies on output of the gradle task and env var QAWOLF_API_KEY
       qawolf
     end
   end

7. Grab a team API key from staging by going to the team settings page. You can find it under “API Access”, mouseover the “Encrypted” text to copy the value. Set it as an environment variable as described below. Also set an environment variable to override the base URL to target staging instead of production. You can also target a preview environment if desired.

   # The API key is required to be set
   export QAWOLF_API_KEY="qawolf_..."
   # optionally override the base URL
   export QAWOLF_BASE_URL="https://app.qawolf.com"

8. Finally, run the command to build the APK and upload it to QA Wolf.

   bundle exec fastlane upload