Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 269 lines (206 sloc) 8.659 kB
5619759 @jlipps some readme updates
authored
1 Sausage
a469d4a @jlipps Initial commit
authored
2 =======
3
5619759 @jlipps some readme updates
authored
4 Your one-stop shop for everything Selenium + Sauce Labs + PHP. This is a set of
5 classes and libraries that make it easy to run your Selenium tests, either
6 locally or on Sauce Labs. You run the tests with [PHPUnit](http://phpunit.de).
7
8 Sausage comes bundled with [Paraunit](http://github.com/jlipps/paraunit) (for
651d7fa @jlipps update readme
authored
9 running your PHPUnit tests in parallel) and optionally
5619759 @jlipps some readme updates
authored
10 [Sauce Connect](http://saucelabs.com/docs/connect) (for testing locally-hosted
11 sites with Sauce).
12
13 Read the rest of this page for installation and usage instructions designed
14 to help you get the most out of your sausage.
fe4eb8d @jlipps move things to a psr-0 structure
authored
15
91e8617 @jlipps added apache license
authored
16 License
17 -------
18 Sausage is available under the Apache 2 license. See `LICENSE.APACHE2` for more
19 details.
20
5619759 @jlipps some readme updates
authored
21 Quickstart
22 ----------
23 Check out [sausage-bun](http://github.com/jlipps/sausage-bun). It's a one-line
504aa96 @jlipps updated readme for windows users
authored
24 script you can run via curl and PHP to get everything going. For example:
25
26 ```
27 curl -s https://raw.github.com/jlipps/sausage-bun/master/givememysausage.php | php
28 ```
29
30 _Note_: if you are a Windows user who's not using Cygwin, it'll take a little
31 extra work to set you up---please see the [sausage-bun
32 README](http://github.com/jlipps/sausage-bun)
5619759 @jlipps some readme updates
authored
33
34 Manual Install
fe4eb8d @jlipps move things to a psr-0 structure
authored
35 ------------
5619759 @jlipps some readme updates
authored
36 Sausage is distributed as a [Composer](http://getcomposer.org) package via
37 [Packagist](http://packagist.org/),
38 under the package `sauce/sausage`. To get it, add (or update) the `composer.json`
39 file in your project root. A minimal example composer.json would look like:
83f98e2 @jlipps do a recursive obj->array
authored
40
a7dcba2 @jlipps trying for syntax coloring
authored
41 ```json
42 {
43 "require": {
2d4dddf @jlipps don't need min stability warning anymore
authored
44 "sauce/sausage": ">=0.4.0"
45 }
a7dcba2 @jlipps trying for syntax coloring
authored
46 }
47 ```
83f98e2 @jlipps do a recursive obj->array
authored
48
504aa96 @jlipps updated readme for windows users
authored
49 If you haven't already got Composer installed, get it thusly (for *nix/Mac):
5619759 @jlipps some readme updates
authored
50
51 curl -s http://getcomposer.org/installer | php
52
53 Then, install the packages (or `update` if you've already set up Composer):
54
55 php composer.phar install
56
57 This will install Sausage and all its dependences (like PHPUnit, etc...). If
58 you didn't already have the `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment
59 variables set, you'll now need to configure Sausage for use with your Sauce
60 account:
61
500c097 @jlipps change references to 'api key' and make it 'access key'
authored
62 vendor/bin/sauce_config YOUR_SAUCE_USERNAME YOUR_SAUCE_ACCESS_KEY
5619759 @jlipps some readme updates
authored
63
504aa96 @jlipps updated readme for windows users
authored
64 (Or for Windows):
65
500c097 @jlipps change references to 'api key' and make it 'access key'
authored
66 vendor\bin\sauce_config.bat YOUR_SAUCE_USERNAME YOUR_SAUCE_ACCESS_KEY
504aa96 @jlipps updated readme for windows users
authored
67
5619759 @jlipps some readme updates
authored
68 (It's a Composer convention for package binaries to be located in `vendor/bin`;
69 you can always symlink things elsewhere if it's more convenient).
70
76c86b0 @jlipps more sausage docs
authored
71 Requirements
72 ---
73 * Sausage will work on any modern (>= 5.3) PHP installation
74 * Composer's requirements must also be satisfied (unfortunately, I could not
75 find these documented anywhere). Suffice it to say they're normal requirements
76 like the cURL extension, `safe_mode` off, `allow_url_fopen`, etc...
77 * If you're on a Windows machine, you might want to set up all your PHP stuff
78 in [Cygwin](http://cygwin.com)
79
80 Getting Started
81 ----
82 If everything's set up correctly, you should be able to run this:
83
84 vendor/bin/phpunit vendor/sauce/sausage/WebDriverDemo.php
85
504aa96 @jlipps updated readme for windows users
authored
86 (Or for Windows):
87
88 vendor\bin\phpunit.bat vendor\sauce\sausage\WebDriverDemo.php
89
76c86b0 @jlipps more sausage docs
authored
90 And start seeing tests pass. (While the tests are running, you can check on
91 their progress by going to your [Sauce tests
92 page](http://saucelabs.com/tests))
93
94 Running tests in parallel
95 ---
96 Running Selenium tests one at a time is like eating one cookie at a time. Let's
97 do it all at once! Try this:
98
99 vendor/bin/paraunit -p2 --path=vendor/sauce/sausage/WebDriverDemo.php
100
504aa96 @jlipps updated readme for windows users
authored
101 (Or for Windows):
102
103 vendor\bin\paraunit.bat --processes=2 --path=vendor\sauce\sausage\WebDriverDemo.php
104
76c86b0 @jlipps more sausage docs
authored
105 Now they'll finish twice as fast! (And if you get a [Sauce Labs
106 account](http://saucelabs.com/pricing), you can
107 bump up that concurrency to 4, 10, 20, 30, or more!)
108
109 Writing WebDriver tests
110 ---
111 Writing tests for Selenium 2 (WebDriver) is easy and straightforward. Sausage
112 is by default built on top of
113 [PHPUnit_Selenium](http://github.com/sebastianbergmann/phpunit-selenium). All
114 commands that work in `PHPUnit_Extensions_Selenium2TestCase` also work in
115 Sausage's `WebDriverTestCase`. Here's a simple example:
116
a7dcba2 @jlipps trying for syntax coloring
authored
117 ```php
118 <?php
76c86b0 @jlipps more sausage docs
authored
119
a7dcba2 @jlipps trying for syntax coloring
authored
120 require_once 'vendor/autoload.php';
76c86b0 @jlipps more sausage docs
authored
121
a7dcba2 @jlipps trying for syntax coloring
authored
122 class MyAwesomeTestCase extends Sauce\Sausage\WebDriverTestCase
123 {
124 public static $browsers = array(
125 // run FF15 on Vista on Sauce
126 array(
127 'browserName' => 'firefox',
128 'desiredCapabilities' => array(
129 'version' => '15',
130 'platform' => 'VISTA'
76c86b0 @jlipps more sausage docs
authored
131 )
a7dcba2 @jlipps trying for syntax coloring
authored
132 ),
133 // run Chrome on Linux on Sauce
134 array(
135 'browserName' => 'chrome',
136 'desiredCapabilities' => array(
137 'platform' => 'Linux'
138 )
139 )
140 );
141
142 public function setUp()
143 {
144 parent::setUp();
145 $this->setBrowserUrl('http://saucelabs.com/test/guinea-pig');
146 }
147
148 public function testLink()
149 {
150 $link = $this->byId('i am a link');
151 $link->click();
152 $this->assertContains("I am another page title", $this->title());
76c86b0 @jlipps more sausage docs
authored
153 }
a7dcba2 @jlipps trying for syntax coloring
authored
154 }
155 ```
76c86b0 @jlipps more sausage docs
authored
156
157 In this example, we define a set of browsers to use, and run a simple check
158 to make sure that clicking on a link gets us to the expected new page.
159
160 For more examples, check out:
161 * The `WebDriverDemo.php` file in this repository
162 * The documentation for [PHPUnit_Extensions_Selenium2TestCase](http://www.phpunit.de/manual/3.7/en/selenium.html#selenium.selenium2testcase)
163
164 If you're into Selenium 1 (Selenium RC), instead take a look at
165 `SeleniumRCDemo.php`
166
ff35403 @jlipps update readme
authored
167 Sauce Labs API
83f98e2 @jlipps do a recursive obj->array
authored
168 ---
76c86b0 @jlipps more sausage docs
authored
169 Sausage comes bundled with a nice PHP interface to the [Sauce Labs API](https://saucelabs.com/docs/rest):
170
a7dcba2 @jlipps trying for syntax coloring
authored
171 ```php
172 <?php
83f98e2 @jlipps do a recursive obj->array
authored
173
500c097 @jlipps change references to 'api key' and make it 'access key'
authored
174 $s = new Sauce\Sausage\SauceAPI('myusername', 'myaccesskey');
83f98e2 @jlipps do a recursive obj->array
authored
175
a7dcba2 @jlipps trying for syntax coloring
authored
176 $my_details = $s->getAccountDetails();
83f98e2 @jlipps do a recursive obj->array
authored
177
a7dcba2 @jlipps trying for syntax coloring
authored
178 $most_recent_test = $s->getJobs(0)['jobs'][0];
179 $s->updateJob($most_recent_test['id'], array('passed' => true));
f637484 @jlipps do a recursive obj->array
authored
180
a7dcba2 @jlipps trying for syntax coloring
authored
181 $browser_list = $s->getAllBrowsers();
182 foreach ($browser_list as $browser) {
183 $name = $browser['long_name'];
184 $ver = $browser['short_version'];
185 $os = $browser['os'];
186 echo "$name $ver $os\n";
187 }
188 ```
f637484 @jlipps do a recursive obj->array
authored
189
ff35403 @jlipps update readme
authored
190 See `Sauce/Sausage/SauceMethods.php` for the list of Sauce API functions (currently
191 boasting 100% support). Also check out `sauce_api_test.php` for other examples.
192
76c86b0 @jlipps more sausage docs
authored
193 Automatic Test Naming
194 ---
195 By default, Sauce Labs doesn't know how to display the name of your test. Sausage
196 comes up with a good name (`TestClass::testFunction`) and reports it with your
197 test so it's easy to find on your [tests page](http://saucelabs.com/tests).
198
199 Automatic Test Status Reporting
200 ---
201 Since Selenium commands might be successful but your test still fails because
202 of an assertion, there is in principle no way for Sauce Labs to know whether a
203 particular run was a pass or fail. Sausage catches any failed assertions and
204 makes sure to report the status of the test to Sauce after it's complete, so
205 as you're looking at your log of tests you can easily see which passed and which
206 failed.
207
208 SpinAsserts
209 ---
210 SpinAsserts are awesome and [you should really use them](http://sauceio.com/index.php/2011/04/how-to-lose-races-and-win-at-selenium/). Luckily, Sausage comes with a SpinAssert framework built in.
211 Let's say we want to perform a check and we're not exactly sure how quickly the
212 state will change to what we want. We can do this:
213
a7dcba2 @jlipps trying for syntax coloring
authored
214 ```php
215 public function testSubmitComments()
216 {
217 $comment = "This is a very insightful comment.";
218 $this->byId('comments')->click();
219 $this->keys($comment);
220 $this->byId('submit')->submit();
221 $driver = $this;
222
223 $comment_test = function() use ($comment, $driver) {
224 return ($driver->byId('your_comments')->text() == "Your comments: $comment");
225 };
226
227 $this->spinAssert("Comment never showed up!", $comment_test);
228 }
229 ```
76c86b0 @jlipps more sausage docs
authored
230
231 This will submit a comment and wait for up to 10 seconds for the comment to show
232 up before declaring the test failed.
233
234 The `spinWait` function is similar and allows you to wait for a certain
235 condition without necessarily asserting anything of it.
236
237 Sauce Connect
238 ---
651d7fa @jlipps update readme
authored
239 Sauce Connect is a special tunnel-creating binary application (see the [Sauce
240 Connect Docs](http://saucelabs.com/docs/connect)). It is bundled as another
241 composer package (`sauce/connect`), which you can add to your `composer.json`
242 requirements:
243
244 ```json
245 {
246 "require": {
247 "sauce/sausage": ">=0.5",
248 "sauce/connect": ">=3.0"
249 }
250 }
251 ```
252
76c86b0 @jlipps more sausage docs
authored
253 If you've already run `vendor/bin/sauce_config` or otherwise set your Sauce
254 credentials, starting sauce connect is as easy as:
ff35403 @jlipps update readme
authored
255
76c86b0 @jlipps more sausage docs
authored
256 vendor/bin/sauce_connect
ff35403 @jlipps update readme
authored
257
504aa96 @jlipps updated readme for windows users
authored
258 (Or for Windows):
259
260 vendor\bin\sauce_connect.bat
261
76c86b0 @jlipps more sausage docs
authored
262 Run that and you'll be testing against your local test server in no time!
2915a08 @jlipps readme markdown
authored
263
76c86b0 @jlipps more sausage docs
authored
264 Contributors
2915a08 @jlipps readme markdown
authored
265 ---
76c86b0 @jlipps more sausage docs
authored
266 * Jonathan Lipps ([jlipps](http://github.com/jlipps)) (Author)
2915a08 @jlipps readme markdown
authored
267
76c86b0 @jlipps more sausage docs
authored
268 If you have any ideas for Sausage, put them in code and send them my way!
Something went wrong with that request. Please try again.