Skip to content

Commit bb6b3d3

Browse files
jzaeffererjzaefferer
committed
README: Overhaul everything, making usage more clear, add contributing
Adds CONTRIBUTING.md specifically for contributors, not users. Makes installing from npm the primary usage example. Compress the default configuration example. Removes a bunch of newlines to make editing easier. Uses better formatting for parameter lists.
1 parent 4933de6 commit bb6b3d3

File tree

2 files changed

+118
-135
lines changed

2 files changed

+118
-135
lines changed

‎CONTRIBUTING.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## Contributing to browserstack-runner
2+
3+
Your help improving this project is welcome!
4+
5+
## Got a question or problem? Found an issue?
6+
7+
If you have questions about how to use this tool, or you found a bug in the source code or a mistake in the documentation, [file an issue](https://github.com/browserstack/browserstack-runner/issues/new).
8+
9+
## Want to contribute code?
10+
11+
If you found an issue and want to contribute a fix or implement a new feature, send a pull request!
12+
13+
To make changes: [Fork the repo, clone it locally](https://help.github.com/articles/fork-a-repo/), make a branch for your change, then implement it.
14+
15+
Install some dependencies:
16+
17+
npm install
18+
19+
Then run tests with:
20+
21+
npm test
22+
23+
This runs some unit tests (consider adding more to `tests/unit`) and runs some other tools like jshint. Make sure to fix lint issues it finds.
24+
25+
To test your change with another project where you use the tool, use `npm-link`:
26+
27+
# in your browserstack-runner checkout
28+
npm link
29+
# in your project
30+
npm link browserstack-runner
31+
32+
Or do a local install:
33+
34+
# in your project
35+
npm install /path/to/checkout/browserstack-runner
36+
37+
Once done, commit, push the branch to your repo and [create a pull request](https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request).

‎README.md‎

Lines changed: 81 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,124 @@
11
A command line interface to run browser tests over BrowserStack.
22

3-
## Install
4-
Go to the `browserstack-runner` directory.
5-
Install browserstack-runner
3+
## Usage
64

7-
npm -g install
5+
Install globally:
86

9-
or
7+
npm -g install browserstack-runner
108

9+
Then, after setting up the configuration, run tests with:
1110

12-
For development,
11+
browserstack-runner
1312

14-
npm link
13+
You can also install locally and run the local binary:
1514

16-
## Configuration
17-
To run browser tests on BrowserStack infrastructure, you need to
18-
create a `browserstack.json` file in project's root directory (the
19-
directory from which tests are run), by running this command:
20-
21-
browserstack-runner init [preset]
22-
23-
If nothing is provided as `preset` **default** is used.
24-
25-
> Currently only one preset is present: **default**
15+
npm install browserstack-runner
16+
node_modules/.bin/browserstack-runner
2617

27-
### Parameters
28-
29-
- *username*: BrowserStack username
30-
(Alternatively: use `BROWSERSTACK_USERNAME` environment variable)
31-
32-
- *key*: BrowserStack key
33-
(Alternatively: use `BROWSERSTACK_KEY` environment variable)
18+
## Configuration
3419

35-
- *test_path*: Path to the which will execute the tests when opened
36-
in a browser.
20+
To run browser tests on BrowserStack infrastructure, you need to create a `browserstack.json` file in project's root directory (the directory from which tests are run), by running this command:
3721

38-
- *test_framework*: Specify test framework which will execute the tests.
39-
We support qunit, jasmine, jasmine 2.0 and mocha.
22+
browserstack-runner init
4023

41-
- *timeout*: Specify worker timeout with BrowserStack.
24+
### Parameters for `browserstack.json`
4225

43-
- *browsers*: A list of browsers on which tests are to be run.
26+
* `username`: BrowserStack username (Or `BROWSERSTACK_USERNAME` environment variable)
27+
* `key`: BrowserStack [access key](https://www.browserstack.com/accounts/local-testing) (Or `BROWSERSTACK_KEY` environment variable)
28+
* `test_path`: Path to the test page which will run the tests when opened in a browser.
29+
* `test_framework`: Specify test framework which will run the tests. Currently supporting qunit, jasmine, jasmine2 and mocha.
30+
* `timeout`: Specify worker timeout with BrowserStack.
31+
* `browsers`: A list of browsers on which tests are to be run. Find a [list of all supported browsers and platforms on browerstack.com](http://www.browserstack.com/list-of-browsers-and-platforms?product=live).
32+
* `proxy`: Specify a proxy to use for the local tunnel. Object with `host`, `port`, `username` and `password` properties.
4433

45-
A sample configuration file (list: http://www.browserstack.com/list-of-browsers-and-platforms?product=live):
34+
A sample configuration file:
4635

4736
```json
4837
{
4938
"username": "<username>",
50-
"key": "<key>",
51-
"test_framework": "qunit/jasmine/jasmine2/mocha",
39+
"key": "<access key>",
40+
"test_framework": "qunit|jasmine|jasmine2|mocha",
5241
"test_path": ["relative/path/to/test/page1", "relative/path/to/test/page2"],
53-
"browsers": [{
54-
"browser": "firefox",
55-
"browser_version": "15.0",
56-
"device": null,
57-
"os": "OS X",
58-
"os_version": "Snow Leopard"
59-
},
60-
{
61-
"browser": "firefox",
62-
"browser_version": "16.0",
63-
"device": null,
64-
"os": "Windows",
65-
"os_version": "7"
66-
},
67-
{
68-
"browser": "firefox",
69-
"browser_version": "17.0",
70-
"device": null,
71-
"os": "Windows",
72-
"os_version": "8"
73-
},
74-
{
75-
"browser": "ie",
76-
"browser_version": "8.0",
77-
"device": null,
78-
"os": "Windows",
79-
"os_version": "7"
80-
},
81-
{
82-
"browser": "ie",
83-
"browser_version": "9.0",
84-
"device": null,
85-
"os": "Windows",
86-
"os_version": "7"
87-
},
88-
{
89-
"os": "android",
90-
"os_version": "4.0",
91-
"device": "Samsung Galaxy Nexus"
92-
},
93-
{
94-
"os": "ios",
95-
"os_version": "7.0",
96-
"device": "iPhone 5S"
97-
},
98-
{
99-
"browser": "ie",
100-
"browser_version": "10.0",
101-
"device": null,
102-
"os": "Windows",
103-
"os_version": "8"
104-
}]
105-
}
106-
```
107-
108-
#### Compact `browsers` configuration
109-
110-
Alternatively, if `os` and `os_version` granularity is not desired, following configuration can be used:
111-
- *browser*_current or *browser*_latest: will assign the latest version of the *browser*.
112-
- *browser*_previous: will assign the previous version of the *browser*.
113-
- *browser*_*version*: will assign the *version* specificed of the *browser*. Minor versions can be concatinated with underscore.
114-
115-
Example:
116-
```json
117-
"browsers": [
118-
"chrome_previous",
119-
"chrome_latest",
120-
"firefox_previous",
121-
"firefox_latest",
122-
"ie_6",
123-
"ie_11",
124-
"opera_12_1",
125-
"safari_5_1",
42+
"browsers": [
12643
{
12744
"browser": "ie",
12845
"browser_version": "10.0",
12946
"device": null,
13047
"os": "Windows",
13148
"os_version": "8"
49+
},
50+
{
51+
"os": "android",
52+
"os_version": "4.0",
53+
"device": "Samsung Galaxy Nexus"
54+
},
55+
{
56+
"os": "ios",
57+
"os_version": "7.0",
58+
"device": "iPhone 5S"
13259
}
133-
]
60+
]
61+
}
13462
```
13563

136-
### Enviroment variables
137-
138-
* `BROWSERSTACK_USERNAME`:
139-
BrowserStack user name.
64+
#### Compact `browsers` configuration
14065

141-
* `BROWSERSTACK_KEY`:
142-
BrowserStack key.
66+
When `os` and `os_version` granularity is not desired, following configuration can be used:
67+
* `[browser]_current` or *browser*_latest: will assign the latest version of the *browser*.
68+
* `[browser]_previous`: will assign the previous version of the *browser*.
69+
* `[browser]_[version]`: will assign the *version* specificed of the *browser*. Minor versions can be concatinated with underscores.
14370

144-
* `TUNNEL_ID`:
145-
Identifier for the current instance of the tunnel process. In `TRAVIS` setup `TRAVIS_JOB_ID` will be the default identifier.
71+
This can also be mixed with fine-grained configuration.
14672

147-
* `BROWSERSTACK_JSON`:
148-
Path to the browserstack.json file. If null, `browserstack.json` in the root directory will be used.
73+
Example:
74+
```json
75+
{
76+
"browsers": [
77+
"chrome_previous",
78+
"chrome_latest",
79+
"firefox_previous",
80+
"firefox_latest",
81+
"ie_6",
82+
"ie_11",
83+
"opera_12_1",
84+
"safari_5_1",
85+
{
86+
"browser": "ie",
87+
"browser_version": "10.0",
88+
"device": null,
89+
"os": "Windows",
90+
"os_version": "8"
91+
}
92+
]
93+
}
94+
```
14995

15096
### Proxy support for BrowserStack local
97+
15198
Add the following in `browserstack.json`
15299
```json
153-
...
154-
"proxy": {
155-
"host": "localhost",
156-
"port": 3128,
157-
"username": "foo",
158-
"password": "bar"
100+
{
101+
"proxy": {
102+
"host": "localhost",
103+
"port": 3128,
104+
"username": "foo",
105+
"password": "bar"
106+
}
159107
}
160-
...
161108
```
162109

163-
### Secure Information
110+
### Supported environment variables
111+
112+
To avoid duplication of system or user specific information across several configuration files, use these environment variables:
164113

165-
To prevent checking in the BrowserStack `username` and `key` in your
166-
source control, the corresponding environment variables can be used.
114+
* `BROWSERSTACK_USERNAME`: BrowserStack user name.
115+
* `BROWSERSTACK_KEY`: BrowserStack key.
116+
* `TUNNEL_ID`: Identifier for the current instance of the tunnel process. In `TRAVIS` setup `TRAVIS_JOB_ID` will be the default identifier.
117+
* `BROWSERSTACK_JSON`: Path to the browserstack.json file. If null, `browserstack.json` in the root directory will be used.
167118

168-
The environment variables then can be safely provided in the build
169-
configuration. For example, with travis-ci you can follow:
170119

171-
http://about.travis-ci.org/docs/user/build-configuration/#Secure-environment-variables
120+
### Secure Information
172121

173-
## Running tests
174-
Run `browserstack-runner` to run the tests on all the browsers mentioned
175-
in the configuration.
122+
To avoid checking in the BrowserStack `username` and `key` in your source control system, the corresponding environment variables can be used.
176123

177-
You can include this in your test script to automatically run cross
178-
browser tests on every build.
124+
These can also be provided by a build server, for example [using secure environment variables on Travis CI](http://about.travis-ci.org/docs/user/build-configuration/#Secure-environment-variables).

0 commit comments

Comments
 (0)