Automates Browser Testing on AWS Device Farm.
This GitHub Action allows you to interact with desktop browser testing on AWS Device Farm. For example, testing new versions of code being committed to a branch to ensure the App works as desired before proceeding with the next step in the release cycle.
- AWS Device Farm Browser Testing for GitHub Actions
- Table of Contents
- Input options
- Output options
- Examples of Usage
- Before each of the following examples, make sure to include the following
- Creating a new AWS Device Farm Project
- Lookup an existing AWS Device Farm Project
- Generate a Test Grid URL for an existing AWS Device Farm Project
- Retrieve All artifacts
- Retrieve VIDEO and LOG artifacts
- Putting it all together with webdriver.io to execute the tests
- Putting it all together more generically using the Test Grid Url mode
- Credentials
- Permissions
- License Summary
- Security Disclosures
- 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,gridurlwhen you wish to generate a Grid URL, orartifact, when you require retrieval of artifacts from an existing AWS Device Farm Project ARN. - 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 nameTest. 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. - url-expires-seconds: OPTIONAL Lifetime, in seconds, of the Test Grid URL. Defaults to 900 if not specified.
- artifact-types: OPTIONAL A comma-delimited list of artifacts to be downloaded after the run completes. The valid values can be found here. No artifacts will be downloaded if this property is not supplied.
- artifact-folder: OPTIONAL The name of the folder where the artifacts are downloaded. Defaults to 'artifacts' if not specified.
- console-url: The AWS Console URL for the Test Grid Project
- project-arn: The ARN of the AWS Device Farm Browser Testing Project
- grid-url: The AWS Device Farm Test Grid URL (only available in gridurl mode)
- grid-url-expires: The Datetime that the supplied grid-url will expire formatted as YYYY-MM-DDThh:mm:ss.fffZ
This action is designed to be used in three different ways.
- Create or lookup an AWS Device Farm Project ARN
- Generate a Test Grid URL for a specified a AWS Device Farm Project
- Retrieve all the Artifacts for all sessions for a specific AWS Device Farm Project
NOTE:
The value of
role-to-assumeshould be replaced with the AWS IAM Role to be used.The value of
aws-regionshould be replaced with the AWS Region being used. Please note that AWS Device Farm is currently only available in the us-west-2 region.For more information on how to configure the
configure-aws-credentialsaction please check here.
- name: Checkout repo
uses: actions/checkout@v3
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v2 # More information on this action can be found below in the 'AWS Credentials' section
with:
role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
aws-region: us-west-2 - name: Create Device Farm Project
id: project
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: project
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }} - name: Lookup Device Farm Project
id: project
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: project
project-arn: Test # A Project with name 'Test' already exists in the AWS Account in this case. - name: Generate Test Grid URL
id: gridurl
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: gridurl
project-arn: Test # A Project with name 'Test' already exists in the AWS Account in this case. - name: Retrieve Device Farm Project Artifacts
id: artifacts
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: artifact
project-arn: Test
artifact-types: ALL
artifact-folder: deviceFarm
- uses: actions/upload-artifact@v3
if: always() # This ensures the artifacts are uploaded even if the Test Run Fails
with:
name: AutomatedTestOutputFiles
path: deviceFarm - name: Retrieve Device Farm Project Artifacts
id: artifacts
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: artifact
project-arn: Test
artifact-types: VIDEO,LOG
- uses: actions/upload-artifact@v3
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
with:
name: AutomatedTestOutputFiles
path: artifactsNOTE:
Examples on how to configure your repository to use webdriver.io can be found here.
- name: Create Device Farm Project
id: project
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: project
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
- name: Install
run: npm install
- name: Test
run: npm run test
env:
PROJECT_ARN: ${{ steps.project.outputs.project-arn }}
- name: Retrieve Device Farm Project Artifacts
id: artifacts
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
with:
mode: artifact
project-arn: ${{ steps.project.outputs.project-arn }}
artifact-types: ALL
- uses: actions/upload-artifact@v3
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
with:
name: AutomatedTestOutputFiles
path: artifacts - name: Create Device Farm Project and generate Grid URL
id: project
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
mode: gridurl
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}
- name: Test
run: **TEST EXCUTION SCRIPT COMMAND HERE**
env:
GRID_URL: ${{ steps.project.outputs.grid-url }}
GRID_URL_EXPIRES: ${{ steps.project.outputs.grid-url-expires }}
- name: Retrieve Device Farm Project Artifacts
id: artifacts
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
with:
mode: artifact
project-arn: ${{ steps.project.outputs.project-arn }}
artifact-types: ALL
- uses: actions/upload-artifact@v3
if: always() # This ensures the artifacts are retrieved even if the test(s) fails
with:
name: AutomatedTestOutputFiles
path: artifactsThis action relies on the default behaviour of the AWS SDK for JavaScript to determine AWS credentials and region. Use the aws-actions/configure-aws-credentials action to configure the GitHub Actions environment with a role using GitHub's OIDC provider and your desired region.
NOTE: AWS Device Farm is available in
us-west-2region only. Therefore, it is important to specifyus-west-2as the value of theaws-regionproperty in theconfigure-aws-credentialsstep.
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v2
with:
role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
aws-region: us-west-2
- name: Create Device Farm Project
id: project
uses: aws-actions/aws-devicefarm-browser-testing@v2.0
with:
project-arn: GitHubAction_${{ github.run_id }}_${{ github.run_attempt }}We recommend following Amazon IAM best practices when using AWS services in GitHub Actions workflows, including:
- Assume an IAM role to receive temporary credentials. See the Sample IAM Role CloudFormation Template in the
aws-actions/configure-aws-credentialsaction to get an example. - Grant least privilege to the IAM role used in GitHub Actions workflows. Grant only the permissions required to perform the actions in your GitHub Actions workflows. See the Permissions section below for the permissions required by this action.
- Monitor the activity of the IAM role used in GitHub Actions workflows.
This action requires the following minimum set of permissions to run an Automated Test:
NOTE:
${Account} should be replaced with the AWS Account Id where the test will run
${ProjectId} should be replaced with the Id of the AWS Device Farm Project being used if you wish to restrict the action to only one project, otherwise replace this with a
*.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"devicefarm:ListTestGridProjects",
"devicefarm:CreateTestGridProject"
],
"Resource": "*"
}
]
}{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"devicefarm:ListTestGridProjects"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"devicefarm:CreateTestGridUrl"
],
"Resource": "arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}"
}
]
}{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"devicefarm:ListTestGridProjects"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"devicefarm:ListTestGridSessions"
],
"Resource": "arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}"
},
{
"Effect": "Allow",
"Action": [
"devicefarm:ListTestGridSessionArtifacts"
],
"Resource": [
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-project:${ProjectId}",
"arn:aws:devicefarm:us-west-2:${Account}:testgrid-session:${ProjectId}/*"
]
}
]
}This code is made available under the MIT license.
If you would like to report a potential security issue in this project, please do not create a GitHub issue. Instead, please follow the instructions here or email AWS security directly.