Skip to content

Commit ec3ffe4

Browse files
francisffrancisf
authored
Merge pull request #2 from rchougule/README_update
README for each action
2 parents 5256c0d + 1c54102 commit ec3ffe4

File tree

3 files changed

+184
-5
lines changed

3 files changed

+184
-5
lines changed

‎README.md

+68-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,69 @@
1-
BrowserStack Actions
1+
# BrowserStack GitHub Actions
22

3-
1. Setup Test Environment: [Readme](./setup-env/README.md)
4-
2. Local Binary Setup: [Readme](./setup-local/README.md)
3+
This respository contains a library of GitHub Actions to help you integrate your test suite with the [BrowserStack](https://browserstack.com) device cloud.
4+
5+
You need a BrowserStack username and access-key to run your tests on the BrowserStack device cloud. You can [sign-up for free trial](https://www.browserstack.com/users/sign_up) if you do not have an existing account.
6+
7+
If you want to test your open source project on BrowserStack, then [sign-up here](https://www.browserstack.com/open-source) for lifetime free access to all our products.
8+
9+
## Available Actions
10+
* [setup-env](./setup-env): This Action helps in setting up the required environment variables that are to be used in your test scripts. The environment variables set up here shall be used by other BrowserStack actions as well for their functioning.
11+
12+
* [setup-local](./setup-local): This Action downloads and starts the appropriate BrowserStackLocal binary, thereby creating a secure tunnel connection from the GitHub Actions runner environment to the BrowserStack device cloud. This secure tunnel will be used by the remote browsers in BrowserStack to access your web application hosted in the GitHub Actions runner environment. **You do not need this Action if the application to be tested is accessible over the public internet.**
13+
14+
## Pre-requisites
15+
* You should set your BrowserStack Username and Access Key as GitHub Secrets, i.e. `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` respectively.
16+
17+
## Usage
18+
As this is a library of Actions, invoking this Action will trigger the `setup-env` Action internally. The following usage example will **only** set up the required environment variables:
19+
20+
```yaml
21+
- name: BrowserStack Action
22+
uses: 'browserstack/github-actions@master'
23+
with:
24+
username: ${{ secrets.BROWSERSTACK_USERNAME }}
25+
access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
26+
build-name: BUILD_INFO
27+
project-name: REPO_NAME
28+
```
29+
We recommend you to invoke the Actions individually depending on the use case. A sample workflow for the same is shown below. You can additionally refer to the individual `README` ([setup-env](./setup-env), [setup-local](./setup-local)) of the Actions to know more about how they work, the inputs they support and their usage examples.
30+
31+
## Sample Workflow with usage of both Actions
32+
The workflow example below would be useful when the web application to be tested is hosted on the GitHub Actions runner environment, i.e. not accessible from the public Internet.
33+
34+
```yaml
35+
name: 'BrowserStack Test'
36+
on: [push, pull_request]
37+
38+
jobs:
39+
ubuntu-job:
40+
name: 'BrowserStack Test on Ubuntu'
41+
runs-on: ubuntu-latest
42+
steps:
43+
- name: 'BrowserStack Env Setup'
44+
uses: 'browserstack/github-actions/setup-env@master'
45+
with:
46+
username: ${{ secrets.BROWSERSTACK_USERNAME }}
47+
access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
48+
build-name: BUILD_INFO
49+
project-name: REPO_NAME
50+
- name: 'BrowserStackLocal Setup'
51+
uses: 'browserstack/github-actions/setup-local@master'
52+
with:
53+
local-testing: start
54+
local-identifier: random
55+
```
56+
57+
### Note
58+
---
59+
Post these steps, you will have to build and run your application web server on the same runner environment. Further, invoke your test scripts by utilizing the environment variables that have been set by actions. For more detailed steps on how to integrate your test suite with BrowserStack on GitHub Actions, visit [BrowserStack Documentation](http://browserstack.com/docs/automate/selenium/github-actions) for the same.
60+
61+
After you are done running your tests, invoke the `setup-local` Action again with `local-testing: stop` as the input:
62+
```yaml
63+
- name: 'BrowserStackLocal Stop'
64+
uses: 'browserstack/github-actions/setup-local@master'
65+
with:
66+
local-testing: stop
67+
```
68+
## Feature requests and bug reports
69+
Please file feature requests and bug reports as [github issues](https://github.com/browserstack/github-actions/issues).

‎setup-env/README.md

+59-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,59 @@
1-
README for Setup BrowserStack Test Environment
1+
# setup-env
2+
3+
This action sets up the following environment variables in the runner environment. These environment variables shall be used in the tests for BrowserStack:
4+
5+
1. `BROWSERSTACK_BUILD_NAME`: This environment variable is set on the basis of the input to `build-name` field. By default, the value will be decided based on the event, i.e. push, pull_request etc for the workflow:
6+
1. `push` event: `[<Branch-Name>] Commit <commit-sha>: <commit-message> [Workflow: <Workflow-number>]`
7+
2. `pull_request` event: `[<Branch-Name>] PR <PR-number>: <PR-title> [Workflow: <Workflow-number>]`
8+
3. `release` event: `[<Branch-Name>] Release <Release-tag>: <Release-name> [Workflow: <Workflow-number>]`
9+
4. Other events: `<Event-Name> [Workflow: <Workflow-number>]`
10+
11+
2. `BROWSERSTACK_PROJECT_NAME`: This environment variable is set on the basis of the input to `project-name` field. By default, i.e. if any input is not provided, the value will be set as the Repository Name.
12+
3. `BROWSERSTACK_USERNAME`: This environment variable's value is taken from the input to `username` field. Ideal way would be to pass the GitHub Secret as the input, i.e. `username: ${{ secrets.BROWSERSTACK_USERNAME }}`.
13+
4. `BROWSERSTACK_ACCESS_KEY`: This environment variable's value is taken from the input to `access-key` field. Ideal way would be to pass the GitHub Secret as the input, i.e. `access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}`.
14+
15+
## Prerequisites
16+
* This action does not have any prerequisites.
17+
18+
## Usage
19+
```yaml
20+
- name: 'BrowserStack Env Setup'
21+
uses: 'browserstack/github-actions/setup-env@master'
22+
with:
23+
username: ${{ secrets.BROWSERSTACK_USERNAME }}
24+
access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
25+
build-name: BUILD_INFO
26+
project-name: REPO_NAME
27+
```
28+
29+
or
30+
31+
```yaml
32+
- name: 'BrowserStack Env Setup'
33+
uses: 'browserstack/github-actions/setup-env@master'
34+
with:
35+
username: ${{ secrets.BROWSERSTACK_USERNAME }}
36+
access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
37+
```
38+
39+
## Inputs
40+
* `username`: (**Mandatory**) This is your BrowserStack Username. This should ideally be passed via a GitHub Secret as shown in the sample workflow above.
41+
* `access-key`: (**Mandatory**) This is your BrowserStack Access key that is required to access the BrowserStack device cloud. This should also ideally be passed via a GitHub Secret as shown in the sample workflow above.
42+
* `build-name`: (**Optional**)
43+
* You can pass any string that you want to set as the `BROWSERSTACK_BUILD_NAME`. E.g. `build-name: My Build Name Goes Here`.
44+
* You can also include your personalized string along with the keyword `BUILD_INFO` in the input:
45+
* `build-name: My String Goes Here - BUILD_INFO`
46+
* `build-name: BUILD_INFO - My String at the end`
47+
* `build-name: String at the Beginning - BUILD_INFO - String at the end`
48+
* The keyword `BUILD_INFO` will be replaced by the information based on the event of the workflow as described above for `BROWSERSTACK_BUILD_NAME` environment variable.
49+
* `project-name`: (**Optional**)
50+
* You can pass any string that you want to set as the `BROWSERSTACK_PROJECT_NAME`. E.g. `project-name: My Project Name Goes Here`.
51+
* You can also pass the keyword `REPO_NAME` as the input. This will set the Repository Name for the `BROWSERSTACK_PROJECT_NAME` environment variable.
52+
* If no input is provided, `REPO_NAME` will be considered as the default input.
53+
54+
---
55+
**NOTE**
56+
* This action is a prerequisite for any other BrowserStack related actions.
57+
* This action should be invoked prior to the execution of tests on BrowserStack to be able to utilise the environment variables in your tests.
58+
* You have to use the environment variables set by this action in your test script.
59+
---

‎setup-local/README.md

+57-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,57 @@
1-
README for Setup BrowserStack Local Binary
1+
# setup-local
2+
This action fulfils the following objectives in your runner environment:
3+
* It will download the appropriate type of BrowserStackLocal binary in your runner environment depending on the environment, i.e. Linux/Darwin/Win32.
4+
* It will start (or stop) the binary and establish (or end) the Local tunnel connection from the runner machine to the BrowserStack cloud as per the input for `local-testing` field.
5+
* The action provides the functionality to specify the logging level of the binary and then upload the logs as artifacts in GitHub workflow.
6+
* The action allows you to pass any combination of arguments for the invocation of the BrowserStackLocal binary as given [here](https://www.browserstack.com/local-testing/binary-params).
7+
8+
## Prerequisites
9+
The **browserstack/github-actions/setup-env@master** action should have been invoked prior to invoking this action as a part of the same job.
10+
11+
## Inputs
12+
* `local-testing`: (**Mandatory**)
13+
* Valid inputs:
14+
* `start`: This will download the BrowserStackLocal binary (if it wasn't downloaded earlier by this action in the same runner environment) and start the binary with additional inputs that you might provide. The `local-identifier` that is used to start the binary will be set in the environment variable `BROWSERSTACK_LOCAL_IDENTIFIER`. The same will be used for stopping the binary when using the `stop` input.
15+
* `stop`: This will ensure that a previously running binary will be stopped and if any log-level was set by `local-logging-level`, then the logs will be uploaded as artifacts. **If you do not stop the binary after the completion of your tests, the logs will not be uploaded as artifacts.**
16+
* `local-logging-level`: (**Optional**)
17+
* Valid inputs:
18+
* `false`: No local binary logs will be captured.
19+
* `setup-logs`: Local logs to debug issues related to setting up of connections will be saved. They will be uploaded as artifacts only if the action is again invoked with `local-testing: stop`.
20+
* `network-logs`: Local logs related to network information will be saved. They will be uploaded as artifacts only if the action is again invoked with `local-testing: stop`.
21+
* `all-logs`: Local logs related to all communication to local servers for each request and response will be saved. They will be uploaded as artifacts only if the action is again invoked with `local-testing: stop`.
22+
* Default: `false`.
23+
* `local-identifier`: (**Optional**)
24+
* Valid inputs:
25+
* `random`: This is the recommended value for this input. A randomly generated string will be used to start the local tunnel connection and the string will be saved in the environment variable `BROWSERSTACK_LOCAL_IDENTIFIER`. You must use the same environment variable in your test script to specify the tunnel identifier in capabilities.
26+
* `<string>`: You can choose any value for the `string`. The same will be saved in the environment variable `BROWSERSTACK_LOCAL_IDENTIFIER` which you must use in your test script to specify the tunnel identifier in capabilities.
27+
* Default: If you do not provide any input, then no tunnel identifier will be used. This option is not recommended because if multiple tunnels are created without any identifier (or with same identifier) for the same access-key, then tests might behave abnormally. It is strongly advised not to choose this option.
28+
* `local-args`: (**Optional**)
29+
* Valid input: You can choose to pass any additional arguments to start the local binary through this option. All your arguments must be a part of this single string. You can find the complete list of supported local-binary arguments [here](https://www.browserstack.com/local-testing/binary-params).
30+
* E.g. `local-args: --force-local --proxy-host <HOST> --proxy-port <PORT> --proxy-user <USER> --proxy-pass <PASSWORD>`
31+
* **NOTE**: Do not include the following arguments as a part of this input string (they will be ignored if passed):
32+
* `--key` or `-k`
33+
* `--local-identifier`
34+
* `--daemon`
35+
* `--only-automate`
36+
* `--verbose`
37+
* `--log-file`
38+
* The above arguments are already being included in the invocation of the local binary and hence, if you include any of the above again in the `local-args` string, they will be ignored. `local-args` is an optional argument and under normal circumstances, if the application is not hosted behind any proxy, this input would not be required. Visit [this page](https://www.browserstack.com/local-testing/binary-params) to see if any additional argument is applicable to your test scenario.
39+
40+
## Usage
41+
Use the code snippet below in your workflow to start the BrowserStackLocal binary and establish the tunnel connection:
42+
```yaml
43+
- name: 'Start BrowserStackLocal Tunnel'
44+
uses: 'browserstack/github-actions/setup-local@master'
45+
with:
46+
local-testing: start
47+
local-logging-level: all-logs
48+
local-identifier: random
49+
```
50+
51+
Use the code snippet below at the end of your workflow after the tests have completed. This will stop the BrowserStackLocal binary and upload the local binary logs (if any):
52+
```yaml
53+
- name: 'Stop BrowserStackLocal'
54+
uses: 'browserstack/github-actions/setup-local@master'
55+
with:
56+
local-testing: stop
57+
```

0 commit comments

Comments
 (0)