Skip to main content

iOS

Requirements​

  1. Xcode (using this version)
  2. iOS and watchOS simulator runtimes installed
  3. An iPhone simulator set up (check model and version to make/run snapshots)

Setup​

  1. Clone the repository:

    $ git clone https://github.com/bitwarden/ios

  2. Install Homebrew dependencies from the repository root:

    $ brew bundle

    Note The dependencies are listed in the Brewfile. Scripts/bootstrap.sh checks that they are installed, so re-run brew bundle if bootstrapping reports missing dependencies.

  3. Bootstrap the project:

    $ Scripts/bootstrap.sh

    Note Because Scripts/bootstrap.sh is how the project is generated, bootstrap.sh will need to be run every time the project configuration or file structure has changed (for example, when files have been added, removed or moved). It is typically best practice to run bootstrap.sh any time you switch branches or pull down changes.

    If you're using swiftly to manage Swift versions, some packages require a different Swift version than the default one, which can cause conflicts. If you see related errors, try swiftly run Scripts/bootstrap.sh +xcode.

    Alternatively, you can create git hooks to automatically execute the bootstrap.sh script every time a git hook occurs. To use the git hook scripts already defined in the Scripts directory, copy the scripts to the .git/hooks directory.

    $ cp Scripts/post-merge .git/hooks/
    $ cp Scripts/post-checkout .git/hooks/

    Also, if the installed Xcode version does not match the expected version, you will receive a warning, which can help with troubleshooting. That warning looks like this:

    🟡 Xcode version mismatch!
    Required version: 26.0.1
    Current version: 16.4

  4. (Optional) Install fastlane if you're developing or testing CI and automation workflows locally:

    Note We manage non-system Ruby installations with rbenv as homebrew tends to break the required Ruby dependencies

    $ brew install rbenv
    $ rbenv init

    From the repository root, run:

    $ rbenv install -s
    $ bundle install

    Note If bundle install fails you may need to restart your shell or source your appropriate profile to recognize the newly installed non-system Ruby, e.g. source ~/.zprofile then bundle install again

    Once complete you can test fastlane with:

    $ bundle exec fastlane --version

    If you see an error that a Ruby version is not installed, or that you should run bundle install, re-run rbenv install -s and bundle install from the repository root.

    Note Only run bundle update when you intend to upgrade the project's Ruby dependencies. It resolves the newest gem versions allowed by the Gemfile and rewrites Gemfile.lock, which then needs to be committed.

    If you're still having issues, here are some helpful commands for troubleshooting:

    $ which -a ruby
    $ which -a rbenv
    $ which -a fastlane
    $ rbenv which fastlane
    $ echo $PATH

Run the app​

  1. Open the project in Xcode.
  2. Run the app in the Simulator with the Bitwarden target for the Password Manager app or Authenticator for the Authenticator app.

[!TIP] To open the workspace in Xcode, go to the repository root and run:

open Bitwarden.xcworkspace

Running tests​

Due to slight snapshot test variations between iOS versions, the test target requires running in an iPhone 16 Pro simulator (iOS 18.1).

  1. In Xcode's toolbar, select the project and a connected device or simulator.

    • The Generic iOS Device used for builds will not work for testing.

  2. In Xcode's menu bar, select Product > Test.

    • Test results appear in the Debug Area, which can be accessed from View > Debug Area > Show Debug Area if not already visible.

Linting​

This project is linted using both SwiftLint and SwiftFormat. Both tools run in linting mode with every build of the Bitwarden target. However, if you would like to have SwiftFormat autocorrect any issues that are discovered while linting, you can manually run the fix command mint run swiftformat ..

Additionally, if you would like SwiftFormat to autocorrect any issues before every commit, you can use a git hook script. To use the git hook script already defined in the Scripts directory, copy the script to the .git/hooks directory.

$ cp Scripts/pre-commit .git/hooks/