Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Some cleanup and additional images

  • Loading branch information...
commit 55219b4ffea9aba789f2640e8cffe0f34a399ba6 1 parent b1d2ec2
@efirestone efirestone authored
View
8 Documentation/Examples/Testable/Testable.xcodeproj/project.pbxproj
@@ -7,6 +7,8 @@
objects = {
/* Begin PBXBuildFile section */
+ AA0A22A913A7D368004789C0 /* KIFTestStep+EXAdditions.m in Sources */ = {isa = PBXBuildFile; fileRef = AAC634C313A68BF000634049 /* KIFTestStep+EXAdditions.m */; };
+ AA0A22AA13A7D372004789C0 /* EXTestController.m in Sources */ = {isa = PBXBuildFile; fileRef = AAB073E513997527008AF393 /* EXTestController.m */; };
AAB073AD139861C0008AF393 /* UIKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = AAB073AC139861C0008AF393 /* UIKit.framework */; };
AAB073AF139861C0008AF393 /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = AAB073AE139861C0008AF393 /* Foundation.framework */; };
AAB073B1139861C0008AF393 /* CoreGraphics.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = AAB073B0139861C0008AF393 /* CoreGraphics.framework */; };
@@ -26,8 +28,6 @@
AAB073DA13994E20008AF393 /* MainWindow.xib in Resources */ = {isa = PBXBuildFile; fileRef = AAB073BE139861C0008AF393 /* MainWindow.xib */; };
AAB073DB13994E20008AF393 /* RootViewController.xib in Resources */ = {isa = PBXBuildFile; fileRef = AAB073C4139861C0008AF393 /* RootViewController.xib */; };
AAC634C113A5EAF900634049 /* KIFTestScenario+EXAdditions.m in Sources */ = {isa = PBXBuildFile; fileRef = AAC634BE13A5E8E200634049 /* KIFTestScenario+EXAdditions.m */; };
- AAC634C513A68C1800634049 /* KIFTestStep+EXAdditions.m in Sources */ = {isa = PBXBuildFile; fileRef = AAC634C313A68BF000634049 /* KIFTestStep+EXAdditions.m */; };
- AAE8772A139DB23B0072C252 /* EXTestController.m in Sources */ = {isa = PBXBuildFile; fileRef = AAB073E513997527008AF393 /* EXTestController.m */; };
AAE8773B139DC07F0072C252 /* libKIF.a in Frameworks */ = {isa = PBXBuildFile; fileRef = AAE8773A139DC07F0072C252 /* libKIF.a */; };
/* End PBXBuildFile section */
@@ -240,6 +240,7 @@
AAB073BA139861C0008AF393 /* main.m in Sources */,
AAB073BD139861C0008AF393 /* TestableAppDelegate.m in Sources */,
AAB073C3139861C0008AF393 /* RootViewController.m in Sources */,
+ AA0A22A913A7D368004789C0 /* KIFTestStep+EXAdditions.m in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
@@ -250,9 +251,8 @@
AAB073D113994E20008AF393 /* main.m in Sources */,
AAB073D213994E20008AF393 /* TestableAppDelegate.m in Sources */,
AAB073D313994E20008AF393 /* RootViewController.m in Sources */,
- AAE8772A139DB23B0072C252 /* EXTestController.m in Sources */,
AAC634C113A5EAF900634049 /* KIFTestScenario+EXAdditions.m in Sources */,
- AAC634C513A68C1800634049 /* KIFTestStep+EXAdditions.m in Sources */,
+ AA0A22AA13A7D372004789C0 /* EXTestController.m in Sources */,
);
runOnlyForDeploymentPostprocessing = 0;
};
View
BIN  Documentation/Images/Add Library Sheet.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  Documentation/Images/Add Library.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  Documentation/Images/Duplicate Target Confirmation.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  Documentation/Images/Duplicate Target.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  Documentation/Images/Rename Product.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN  Documentation/Images/Rename Target.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
174 README.md
@@ -3,7 +3,7 @@ KIF iOS Integration Testing Framework
KIF, which stands for Keep It Functional, is an iOS integration test framework. It allows for easy automation of iOS apps by leveraging the accessibility attributes that the OS makes available for those with visual disabilities.
-*KIF uses undocumented Apple APIs.* This is true of most iOS testing frameworks, and is safe for testing purposes, but it's important that KIF does not make it into production code, because it will get your app submission denied by Apple. The instructions below help ensure that your project gets configured correctly.
+*KIF uses undocumented Apple APIs.* This is true of most iOS testing frameworks, and is safe for testing purposes, but it's important that KIF does not make it into production code, as it will get your app submission denied by Apple. Follow the instructions below to ensure that KIF is configured correctly for your project.
Features
--------
@@ -15,7 +15,7 @@ All of the tests for KIF are written in Objective C. This allows for maximum int
KIF integrates directly into your iOS app, so there's no need to run an additional web server or install any additional packages.
#### Test Like a User
-KIF attempts to imitate actual user input as closely as possible. Automation is done using tap events wherever possible.
+KIF attempts to imitate actual user input. Automation is done using tap events wherever possible.
Installation
@@ -28,7 +28,7 @@ To install KIF, you'll need to link the libKIF static library directly into your
### Add KIF to your project files
We'll add the KIF project into the ./Frameworks/KIF subdirectory of your existing app. If your project is stored in GitHub then you can use submodules to make updating in the future easier:
- cd /path/to/MyApplication
+ cd /path/to/MyApplicationSource
mkdir Frameworks
git submodule add git@github.com:/square/KIF Frameworks/KIF
@@ -37,35 +37,51 @@ If you're not using GitHub, simply download the source and copy it into the ./Fr
### Add KIF to Your Workspace
Your app needs to know about KIF. The best way to do this is to add the KIF project into a workspace along with your main project. Find the KIF.xcodeproj file in Finder and drag it into the Project Navigator (⌘+1). If you don't already have a workspace, Xcode will ask if you want to create a new one. Click "Save" when it does.
-![Create workspace screen shot](./Documentation/Images/Create Workspace.png)
+![Create workspace screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Create Workspace.png)
### Create a Testing Target
We'll create a second target for the KIF enabled version of the app to test. This gives us an easy way to begin testing (just run this second target), and also helps make sure that no testing code ever makes it into your App Store submission and gets your app rejected.
-The new target will start as a duplicate of your old target. To create the duplicate target, select the project file for your app in the Project Navigator. From there, CTRL+click the target for your app and select the "Duplicate" option. Xcode may ask you if you want your copy to be for a different iOS device, which we don't, so choose "Duplicate Only". The new target will be created and you can rename it to something like "Integration Tests" if you wish.
+The new target will start as a duplicate of your old target. To create the duplicate target, select the project file for your app in the Project Navigator. From there, CTRL+click the target for your app and select the "Duplicate" option.
+
+![Duplicate target screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Duplicate Target.png)
+
+Xcode may ask you if you want your copy to be for a different iOS device, which we don't, so choose "Duplicate Only".
+
+![Duplicate target confirmation screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Duplicate Target Confirmation.png)
+
+The new target will be created and you can rename it to something like "Integration Tests" if you wish.
+
+![Rename target screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Rename Target.png)
You can also (optionally) rename the new target from the default "MyApp copy" to something like "MyApp (Integration Tests)" by selecting the "Build Settings" tab and searching for "Product Name", then changing the value to what you want.
+![Rename product screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Rename Product.png)
### Configure the Testing Target
Now that we have a target for our tests, we need to add the tests to that target. With the project settings still selected in the Project Navigator, and the new integration tests target selected in the project settings, select the "Build Phases" tab. Under the "Link Binary With Libraries" section, hit the "+" button. In the sheet that appears, select "libKIF.a" and click "Add".
-Next, we'll make sure that we can access the KIF header files. To do this, we'll add the KIF directory into the search path by adding the KIF directory to the "Header Search Paths" build setting. Start by selecting the "Build Settings" tab of the project settings. From there, use the filter control to find the "Header Search Paths" setting. Double click the value, and add the search path "$(SRCROOT)/Frameworks/KIF/" to the list. Mark the entry as recursive. If it's not there already, you should add the "$(inherited)" entry as the first entry in this list.
+![Add libKIF library screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Add Library.png)
+
+![Add libKIF library screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Add Library Sheet.png)
+
+Next, we'll make sure that we can access the KIF header files. To do this, we'll add the KIF directory to the "Header Search Paths" build setting. Start by selecting the "Build Settings" tab of the project settings, and from there, use the filter control to find the "Header Search Paths" setting. Double click the value, and add the search path "$(SRCROOT)/Frameworks/KIF/" to the list. Mark the entry as recursive. If it's not there already, you should add the "$(inherited)" entry as the first entry in this list.
-![Add header search paths](./Documentation/Images/Add Header Search Paths.png)
+![Add header search paths screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Add Header Search Paths.png)
KIF takes advantage of Objective C's ability to add categories on an object, but this isn't enabled for static libraries by default. To enable this, add the "-ObjC" and "-all_load" flags to the "Other Linker Flags" build setting as shown below.
-![Add category linker flags](./Documentation/Images/Add Category Linker Flags.png)
+![Add category linker flags screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Add Category Linker Flags.png)
Finally, we'll add a preprocessor flag to our testing target so that we can conditionally include code. This will help us make sure that none of our testing code makes it into the production app. We'll call the flag "RUN_KIF_TESTS" and we'll add it under the "Preprocessor Macros." Again we'll want to make sure the "$(inherited)" entry is first in the list,
-- set RUN_KIF_TESTS=1
+
+![Add preprocessor macro screen shot](https://github.com/square/KIF/raw/master/Documentation/Images/Add KIF Preprocessor Macro.png)
Example
-------
With your project configured to use KIF, it's time to start writing tests. There are three main classes used in KIF testing: the test runner (KIFTestController), a testable scenario (KIFTestScenario), and a test step (KIFTestStep). The test runner is composed of a list of scenarios that it runs, and in turn each scenario is composed of a list of steps. A step is a small and simple action which is generally used to imitate a user interaction. Three of the most common steps are "tap this view," "enter text into this view," and "wait for this view." These steps are included as factory methods on KIFTestStep in the base KIF implementation.
-KIF relies on the built in accessibility of iOS to perform its test steps. As such, it's important that your app is fully accessible. This is also a great way to ensure that your app is usable by the sight impaired. Making your application accessible is usually as easy as giving your views reasonable labels. More details are available in ![Apple's Documentation](http://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/iPhoneAccessibility/Making_Application_Accessible/Making_Application_Accessible.html#//apple_ref/doc/uid/TP40008785-CH102-SW5).
+KIF relies on the built in accessibility of iOS to perform its test steps. As such, it's important that your app is fully accessible. This is also a great way to ensure that your app is usable by the sight impaired. Making your application accessible is usually as easy as giving your views reasonable labels. More details are available in [Apple's Documentation](http://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/iPhoneAccessibility/Making_Application_Accessible/Making_Application_Accessible.html#//apple_ref/doc/uid/TP40008785-CH102-SW5).
Although not required, it's recommended that you create a subclass of KIFTestController that is specific to your application. This subclass will override the -initializeScenarios method, which will contain a list of invocations for the scenarios that your test suite will run. We'll call our subclass EXTestController, and will add an initial test scenario, which we will define later.
@@ -236,139 +252,25 @@ Everything should now be configured. When you run the integration tests target i
Troubleshooting
---------------
-- Tapping table view cells - need to subclass and add isAccessibilityElement = YES
-
-- Cannot find a view - Make sure it has the proper accessibility label
-- Cannot find KIF classes or headers - Make sure .m file is included in correct target (only)
-
-2011-06-13 13:54:53.295 Testable (Integration Tests)[12385:207] -[NSFileManager createUserDirectory:]: unrecognized selector sent to instance 0x4e02830
-2011-06-13 13:54:53.298 Testable (Integration Tests)[12385:207] *** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: '-[NSFileManager createUserDirectory:]: unrecognized selector sent to instance 0x4e02830'
-
-- Make sure to add library flags
-
-Continuous Integration
-----------------------
-
-
-
-GitHub Markup
-=============
-
-We use this library on GitHub when rendering your README or any other
-rich text file.
-
-Markups
--------
-
-The following markups are supported. The dependencies listed are required if
-you wish to run the library.
-
-* [.markdown](http://daringfireball.net/projects/markdown/) -- `gem install redcarpet`
-* [.textile](http://www.textism.com/tools/textile/) -- `gem install RedCloth`
-* [.rdoc](http://rdoc.sourceforge.net/)
-* [.org](http://orgmode.org/) -- `gem install org-ruby`
-* [.creole](http://wikicreole.org/) -- `gem install creole`
-* [.mediawiki](http://www.mediawiki.org/wiki/Help:Formatting) -- `gem install wikicloth`
-* [.rst](http://docutils.sourceforge.net/rst.html) -- `easy_install docutils`
-* [.asciidoc](http://www.methods.co.nz/asciidoc/) -- `brew install asciidoc`
-* [.pod](http://search.cpan.org/dist/perl/pod/perlpod.pod) -- `Pod::Simple::HTML`
- comes with Perl >= 5.10. Lower versions should install Pod::Simple from CPAN.
-* .1 - Requires [`groff`](http://www.gnu.org/software/groff/)
-
-
-Contributing
-------------
-
-Want to contribute? Great! There are two ways to add markups.
-
-
-### Commands
+### Step fails because a view cannot be found
-If your markup is in a language other than Ruby, drop a translator
-script in `lib/github/commands` which accepts input on STDIN and
-returns HTML on STDOUT. See [rest2html][r2h] for an example.
+If KIF is failing to find a view, the most likely cause is that the view doesn't have its accessibility label set. If the view is defined in a xib, then the label can be set using the inspector. If it's created programmatically, simply set the accessibilityLabel attribute to the desired label.
-Once your script is in place, edit `lib/github/markups.rb` and tell
-GitHub Markup about it. Again we look to [rest2html][r2hc] for
-guidance:
+If the label is definitely set correctly, take a closer look at the error given by KIF. This error should tell you more specifically why the view was not accessible. If you are using -stepToWaitForTappableViewWithAccessibilityLabel:, then make sure the view is actually tappable. For items such as labels which cannot become the first responder, you may need to use -stepToWaitForViewWithAccessibilityLabel: instead.
- command(:rest2html, /re?st(.txt)?/)
+### Project fails to build because KIF classes are missing
-Here we're telling GitHub Markup of the existence of a `rest2html`
-command which should be used for any file ending in `rest`,
-`rst`, `rest.txt` or `rst.txt`. Any regular expression will do.
+If your project doesn't build because the compiler can't find the KIF classes, there are common problems. First, check that the header search paths points to the correct location, as described above. Second, make sure that all of your KIF related implementation files (.m files) are included in the correct target. Select each of the your KIF related files and check the Target Membership section of the inspector on the righthand side of Xcode. For each file, *only* the integration tests target should be checked.
-Finally add your tests. Create a `README.extension` in `test/markups`
-along with a `README.extension.html`. As you may imagine, the
-`README.extension` should be your known input and the
-`README.extension.html` should be the desired output.
+### Unrecognized selector when first trying to run
-Now run the tests: `rake`
+If the first time you try to run KIF you get the following error:
-If nothing complains, congratulations!
+ 2011-06-13 13:54:53.295 Testable (Integration Tests)[12385:207] -[NSFileManager createUserDirectory:]: unrecognized selector sent to instance 0x4e02830
+ 2011-06-13 13:54:53.298 Testable (Integration Tests)[12385:207] *** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: '-[NSFileManager createUserDirectory:]: unrecognized selector sent to instance 0x4e02830'
+or if you get another "unrecognized selector" error inside the KIF code, make sure that you've properly set the -ObjC and -all_load flags as described above. Without these flags your app can't access the category methods that are necessary for KIF to work properly.
-### Classes
-
-If your markup can be translated using a Ruby library, that's
-great. Check out Check `lib/github/markups.rb` for some
-examples. Let's look at Markdown:
-
- markup(:markdown, /md|mkdn?|markdown/) do |content|
- Markdown.new(content).to_html
- end
-
-We give the `markup` method three bits of information: the name of the
-file to `require`, a regular expression for extensions to match, and a
-block to run with unformatted markup which should return HTML.
-
-If you need to monkeypatch a RubyGem or something, check out the
-included RDoc example.
-
-Tests should be added in the same manner as described under the
-`Commands` section.
-
-
-Installation
------------
-
- gem install github-markup
-
-
-Usage
------
-
- require 'github/markup'
- GitHub::Markup.render('README.markdown', "* One\n* Two")
-
-Or, more realistically:
-
- require 'github/markup'
- GitHub::Markup.render(file, File.read(file))
-
-
-Testing
--------
-
-To run the tests:
-
- $ rake
-
-To add tests see the `Commands` section earlier in this
-README.
-
-
-Contributing
-------------
-
-1. Fork it.
-2. Create a branch (`git checkout -b my_markup`)
-3. Commit your changes (`git commit -am "Added Snarkdown"`)
-4. Push to the branch (`git push origin my_markup`)
-5. Create an [Issue][1] with a link to your branch
-6. Enjoy a refreshing Diet Coke and wait
-
+Continuous Integration
+----------------------
-[r2h]: http://github.com/github/markup/tree/master/lib/github/commands/rest2html
-[r2hc]: http://github.com/github/markup/tree/master/lib/github/markups.rb#L13
-[1]: http://github.com/github/markup/issues
Please sign in to comment.
Something went wrong with that request. Please try again.