Skip to content

Commit eb9f3c2

Browse files
danjhddanjhd
committed
update readme (NOT FINISHED)
1 parent 2c13a45 commit eb9f3c2

File tree

1 file changed

+93
-28
lines changed

1 file changed

+93
-28
lines changed

‎README.md

+93-28
Original file line numberDiff line numberDiff line change
@@ -17,15 +17,17 @@ For example, testing new versions of code being committed to a branch to ensure
1717
- [Before each of the following examples, make sure to include the following](#before-each-of-the-following-examples-make-sure-to-include-the-following)
1818
- [Creating a new AWS Device Farm Project](#creating-a-new-aws-device-farm-project)
1919
- [Lookup an existing AWS Device Farm Project](#lookup-an-existing-aws-device-farm-project)
20+
- [Generate a Test Grid URL for an existing AWS Device Farm Project](#generate-a-test-grid-url-for-an-existing-aws-device-farm-project)
2021
- [Retrieve All artifacts](#retrieve-all-artifacts)
2122
- [Retrieve VIDEO and LOG artifacts](#retrieve-video-and-log-artifacts)
2223
- [Putting it all together with webdriver.io to execute the tests](#putting-it-all-together-with-webdriverio-to-execute-the-tests)
24+
- [Putting it all together with Selenium to execute the tests](#putting-it-all-together-with-selenium-to-execute-the-tests)
2325
- [Credentials](#credentials)
2426
- [AWS Credentials](#aws-credentials)
2527
- [Permissions](#permissions)
2628
- [Running the action in `project` mode only](#running-the-action-in-project-mode-only)
29+
- [Running the action in `gridurl` mode only](#running-the-action-in-gridurl-mode-only)
2730
- [Running the action in `artifact` mode only](#running-the-action-in-artifact-mode-only)
28-
- [Optional permissions](#optional-permissions)
2931
- [License Summary](#license-summary)
3032
- [Security Disclosures](#security-disclosures)
3133

@@ -35,19 +37,24 @@ For example, testing new versions of code being committed to a branch to ensure
3537

3638
- mode: **REQUIRED** The mode to execute the action in. Valid values are `project`, when you require creation or looking up of an AWS Device Farm Project ARN, or `artifact`, when you require retrieval of artifacts from an existing AWS Device Farm Project ARN.
3739
- project-arn: **REQUIRED** The name (or arn) of the Device Farm Project. In addition to supporting the value of an ARN of an existing Project, this field supports the use of a **name** as well. For example, if `"project-arn": "Test"` is supplied, the Action will perform a lookup in the AWS Account to find and retrieve the ARN of the AWS Device Farm Project with the name `Test`. If a **name** is supplied but not found a new Project with the supplied name will be created and the ARN of that newly created Project will be used.
40+
- url-expires-seconds: **OPTIONAL** Lifetime, in seconds, of the Test Grid URL. Defaults to 900 if not specified.
3841
- artifact-types: **OPTIONAL** A comma-delimited list of artifacts to be downloaded after the run completes. The valid values can be found [here](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-device-farm/Variable/TestGridSessionArtifactCategory/). No artifacts will be downloaded if this property is not supplied.
3942
- artifact-folder: **OPTIONAL** The name of the folder where the artifacts are downloaded. Defaults to 'artifacts' if not specified.
4043

4144
## Output options
4245

43-
- project-arn: The ARN of the AWS Device Farm Project that was used.
46+
- console-url: The AWS Console URL for the Test Grid Project
47+
- project-arn: The ARN of the AWS Device Farm Browser Testing Project
48+
- grid-url: The AWS Device Farm Test Grid URL (only available in gridurl mode)
49+
- grid-url-expires: The Datetime that the supplied grid-url will expire formatted as YYYY-MM-DDThh:mm:ss.fffZ
4450

4551
## Examples of Usage
4652

47-
This action is designed to be used in two different ways.
53+
This action is designed to be used in three different ways.
4854

4955
1. Create or lookup an AWS Device Farm Project ARN
50-
2. Retrieve all the Artifacts for all sessions for a specific AWS Device Farm Project
56+
2. Generate a Test Grid URL for a specified a AWS Device Farm Project
57+
3. Retrieve all the Artifacts for all sessions for a specific AWS Device Farm Project
5158

5259
### Before each of the following examples, make sure to include the following
5360

@@ -75,7 +82,7 @@ This action is designed to be used in two different ways.
7582
```yaml
7683
- name: Create Device Farm Project
7784
id: project
78-
uses: aws-actions/aws-devicefarm-browser-testing@v1
85+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
7986
with:
8087
mode: project
8188
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
@@ -86,18 +93,29 @@ This action is designed to be used in two different ways.
8693
```yaml
8794
- name: Lookup Device Farm Project
8895
id: project
89-
uses: aws-actions/aws-devicefarm-browser-testing@v1
96+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
9097
with:
9198
mode: project
9299
project-arn: Test # A Project with name 'Test' already exists in the AWS Account in this case.
93100
```
94101
102+
### Generate a Test Grid URL for an existing AWS Device Farm Project
103+
104+
```yaml
105+
- name: Generate Test Grid URL
106+
id: gridurl
107+
uses: aws-actions/[email protected]
108+
with:
109+
mode: gridurl
110+
project-arn: Test # A Project with name 'Test' already exists in the AWS Account in this case.
111+
```
112+
95113
### Retrieve All artifacts
96114
97115
```yaml
98116
- name: Retrieve Device Farm Project Artifacts
99117
id: artifacts
100-
uses: aws-actions/aws-devicefarm-browser-testing@v1
118+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
101119
with:
102120
mode: artifact
103121
project-arn: Test
@@ -116,7 +134,7 @@ This action is designed to be used in two different ways.
116134
```yaml
117135
- name: Retrieve Device Farm Project Artifacts
118136
id: artifacts
119-
uses: aws-actions/aws-devicefarm-browser-testing@v1
137+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
120138
with:
121139
mode: artifact
122140
project-arn: Test
@@ -133,12 +151,12 @@ This action is designed to be used in two different ways.
133151
134152
> **_NOTE:_**
135153
>
136-
> Examples on how to configure your repository to used webdriver.io can be found [here](https://webdriver.io/docs/githubactions/).
154+
> Examples on how to configure your repository to use webdriver.io can be found [here](https://webdriver.io/docs/githubactions/).
137155
138156
```yaml
139157
- name: Create Device Farm Project
140158
id: project
141-
uses: aws-actions/aws-devicefarm-browser-testing@v1
159+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
142160
with:
143161
mode: project
144162
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
@@ -153,7 +171,49 @@ This action is designed to be used in two different ways.
153171

154172
- name: Retrieve Device Farm Project Artifacts
155173
id: artifacts
156-
uses: aws-actions/aws-devicefarm-browser-testing@v1
174+
uses: aws-actions/[email protected]
175+
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
176+
with:
177+
mode: artifact
178+
project-arn: ${{ steps.project.outputs.project-arn }}
179+
artifact-types: ALL
180+
181+
- uses: actions/upload-artifact@v3
182+
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
183+
with:
184+
name: AutomatedTestOutputFiles
185+
path: artifacts
186+
```
187+
188+
### Putting it all together with Selenium to execute the tests
189+
190+
> **_NOTE:_**
191+
>
192+
> Examples on how to configure your repository to use Selenium can be found [here](???).
193+
194+
```yaml
195+
- name: Create Device Farm Project
196+
id: project
197+
uses: aws-actions/[email protected]
198+
with:
199+
mode: project
200+
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
201+
202+
- name: Generate Test Grid URL
203+
id: gridurl
204+
uses: aws-actions/[email protected]
205+
with:
206+
mode: gridurl
207+
project-arn: ${{ steps.project.outputs.project-arn }}
208+
209+
- name: Test
210+
run: '???'
211+
env:
212+
GRID_URL: ${{ steps.gridurl.outputs.grid-url }}
213+
214+
- name: Retrieve Device Farm Project Artifacts
215+
id: artifacts
216+
uses: aws-actions/[email protected]
157217
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
158218
with:
159219
mode: artifact
@@ -184,7 +244,7 @@ This action relies on the [default behaviour of the AWS SDK for JavaScript](http
184244
185245
- name: Create Device Farm Project
186246
id: project
187-
uses: aws-actions/aws-devicefarm-browser-testing@v1
247+
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
188248
with:
189249
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
190250
```
@@ -223,7 +283,7 @@ This action requires the following minimum set of permissions to run an Automate
223283
}
224284
```
225285

226-
### Running the action in `artifact` mode only
286+
### Running the action in `gridurl` mode only
227287

228288
```json
229289
{
@@ -239,27 +299,15 @@ This action requires the following minimum set of permissions to run an Automate
239299
{
240300
"Effect": "Allow",
241301
"Action": [
242-
"devicefarm:ListTestGridSessions"
302+
"devicefarm:CreateTestGridUrl"
243303
],
244304
"Resource": "arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}"
245-
},
246-
{
247-
"Effect": "Allow",
248-
"Action": [
249-
"devicefarm:ListTestGridSessionArtifacts"
250-
],
251-
"Resource": [
252-
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}",
253-
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-session:${ProjectId}/*"
254-
]
255305
}
256306
]
257307
}
258308
```
259309

260-
### Optional permissions
261-
262-
If your GitHub workflow is using the same AWS IAM Role to execute this action and also to run your AWS Device Farm Tests you will the AWS IAM Role will need one further IAM permission. This permission is shown below to make it easier for users, this permission is _not_ required to execute this action itself.
310+
### Running the action in `artifact` mode only
263311

264312
```json
265313
{
@@ -268,9 +316,26 @@ If your GitHub workflow is using the same AWS IAM Role to execute this action an
268316
{
269317
"Effect": "Allow",
270318
"Action": [
271-
"devicefarm:CreateTestGridUrl"
319+
"devicefarm:ListTestGridProjects"
320+
],
321+
"Resource": "*"
322+
},
323+
{
324+
"Effect": "Allow",
325+
"Action": [
326+
"devicefarm:ListTestGridSessions"
272327
],
273328
"Resource": "arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}"
329+
},
330+
{
331+
"Effect": "Allow",
332+
"Action": [
333+
"devicefarm:ListTestGridSessionArtifacts"
334+
],
335+
"Resource": [
336+
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}",
337+
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-session:${ProjectId}/*"
338+
]
274339
}
275340
]
276341
}

0 commit comments

Comments
 (0)