{"id":26817920,"url":"https://github.com/landregistry/skeleton-acceptance-tests","last_synced_at":"2025-04-23T22:46:13.355Z","repository":{"id":40191861,"uuid":"227100611","full_name":"LandRegistry/skeleton-acceptance-tests","owner":"LandRegistry","description":"A Ruby-Cucumber based acceptance tests skeleton framework. Compatible with the HMLR common-dev-env.","archived":false,"fork":false,"pushed_at":"2023-04-12T05:42:35.000Z","size":89,"stargazers_count":4,"open_issues_count":5,"forks_count":3,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-04-23T22:46:00.806Z","etag":null,"topics":["capybara","chromedriver","cucumber","docker","ruby","selenium"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LandRegistry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-10T11:17:28.000Z","updated_at":"2023-12-11T09:00:41.000Z","dependencies_parsed_at":"2023-02-10T18:15:32.291Z","dependency_job_id":null,"html_url":"https://github.com/LandRegistry/skeleton-acceptance-tests","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fskeleton-acceptance-tests","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fskeleton-acceptance-tests/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fskeleton-acceptance-tests/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LandRegistry%2Fskeleton-acceptance-tests/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LandRegistry","download_url":"https://codeload.github.com/LandRegistry/skeleton-acceptance-tests/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250528694,"owners_count":21445511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capybara","chromedriver","cucumber","docker","ruby","selenium"],"created_at":"2025-03-30T04:18:25.347Z","updated_at":"2025-04-23T22:46:13.317Z","avatar_url":"https://github.com/LandRegistry.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Ruby](https://github.com/LandRegistry/skeleton-acceptance-tests/workflows/Ruby/badge.svg?branch=main)\n# Skeleton Acceptance Tests\n\nThis repository is a skeleton to run Cucumber acceptance tests (with [Ruby][1] and [Selenium][2]), as part of the Land Registry [common-dev-env][3].\nThis skeleton includes sample tests written to the HMLR UI Test Standard (Page Object Model pattern).\nThe [wiki][13] contains more detailed information on the rules and examples.\n\nThe tests are written against a test service, built with the [GOV.UK prototype kit][11] hosted on heroku. The [training service][10] has basic functionality and common components found in GOV.UK services.\nThe training service code is hosted on [github][12], and open to contributions.\n\n## Notes\n\n* The gems used for the acceptance tests are contained within the `Gemfile`\n* The `Gemfile.lock` provided contains working gem dependencies.\n* [Ruby Style Guide][4] will provide examples and explanations for linting violations\n* The [docker-base-image v4.1][5] is used to build this skeleton and currently uses:\n    * Ruby version: 2.6.5\n    * Rubygems version: 3.0.6\n    * Bundler version: 2.0.2\n* `support/config.rb` has the skeleton default values and driver configuration\n\n## Architecture\nThe skeleton is composed of a few different technologies.\n\nThe key technologies used are:\n\n* [Cucumber][8]\n* [Ruby][1]\n* [Selenium webdriver][2]\n* [Capybara][6]\n* [Chromedriver][7]\n\n\n![Acceptance test flow](reference_docs/skeleton_architecture.png)\n\n\n*High level acceptance test architecture diagram*\n\n### Description\n\nCucumber feature files (business facing) are written in the english like Gherkin syntax.\nThese link to the step definitions (technical facing), written in Ruby.\n\n\nWhen executed, the Ruby code triggers Capybara actions to interact with the page.\nCapybara acts as a wrapper around Selenium (which really triggers the page interactions).\nCapybara uses acceptance test type language, and is driver agnostic, so you could choose a different webdriver.\n\n    # Cabybara example\n    fill_in('some_field', with: 'some_text')\n\n    # Selenium example\n    driver.findElement(By.id('some_field').sendKeys('some_text'))\n\n\nSelenium talks to Chromedriver which allows automation of a Chrome browser session.\nThe actions are performed against the web application under test.\n\nThe tests are run using headless chrome (you cannot see the browser open, and the tests running)\n\n\n## Adding the skeleton to an existing dev-env\nIf you are already familiar with the [common-dev-env][3] and have an existing dev-env-config\nyou can add the skeleton into your`configuration.yml`.\n\n```yaml\n  skeleton-acceptance-tests:\n    repo: git@github.com:LandRegistry/skeleton-acceptance-tests.git\n    branch: master\n```\n\n## To Run the tests\n* Firstly confirm commands listed below correspond to whats provided in the\n[Common dev-env][3].\nBut defer to the dev-env documentation as the source of truth, in the event of conflicting information.\n\n\n```shell\n# Use common-dev-env alias to execute run_tests.sh within the docker container\nacctest skeleton-acceptance-tests\n```\n\n```shell\n# or use the full command without the common-dev-env alias\ndocker-compose run --rm skeleton-acceptance-tests sh run_tests.sh\n```\n\n ```shell\n# To run only tests with specific tags:\nacctest skeleton-acceptance-tests --tags \"@run_me\"\n```\n ```shell\n# To exclude tests based on tags use \"not\"\nacctest skeleton-acceptance-tests --tags \"not @dont_run_me\"\n```\n\n```shell\n# This can be comibined to run some tags, while excluding others\nacctest skeleton-acceptance-tests --tags \"@included_tag and not @excluded_tag\"\n```\n\n## Rubocop\n* The configuration of Rubocop and any future configuration can be done in:\n  `.rubocop.yml`. Check the `TargetRubyVersion` matches what is running in your environment\n\n* A Rubocop evaluation of the Ruby code must be done during development, with violations resolved\n\n* A standalone run of Rubocop can be done with the following commands:\n\n```shell\n# Use common-dev-env alias to execute run_linting.sh within the docker container\nacclint skeleton-acceptance-tests\n```\nwhich is equivalent to\n\n```shell\nrun skeleton-acceptance-tests sh run_linting.sh\n```\n\nRubocop can attempt to automatically fix any linting issues in your code using the flag `-a`.\n```shell\nrun skeleton-acceptance-tests rubocop -a\n```\n\nIt's better to use this at file or folder level, rather than suite level.\nRubocop can be used to lint a single file, rather than the whole codebase\n\n```shell\nrun skeleton-acceptance-tests rubocop -a {path to your code}\n```\n\n## Automated Accessibility Checks (Axe)\n\nSome automated accessibility checks, can be performed using the axe-matchers gem.\nThese checks will ***not prove a page is accessible***. Manual checks must still be performed.\n\nDo not add axe checks as part of other tests. Tests should be atomic.\nAxe tests should be separate from other acceptance tests.\nExamples can be found in `features/features/accessibility.feature`\n\nTo check a page do the following:\n\n1. Tag the scenario with `@axe`\nThis scenario should only navigate to the page you want to test, and get it into the correct state.\n\n2. Once on the page use this step to run axe\n` Then the page should be accessible according to: wcag2aa`\n\n3. Run all tests tagged with `@axe`\nYou can use any the standard dev-env methods to do this.\n\ne.g. `acctest skeleton-acceptance-tests --tags @axe`\n\n## BrowserStack\nTests can be run remotely on BrowserStack servers as part of your testing.\nThis has added BrowserStack environment variables `BS_*` in the `Dockerfile`, which will need credentials.\nThe full list of what we must test against can be found in [GDS Compatability](https://www.gov.uk/service-manual/technology/designing-for-different-browsers-and-devices),\nand are documented in the provided Desktop configurations `/browser_configs` folder.\n\nTest runs can be checked by logging into [Browserstack dashboard](https://automate.browserstack.com/) looking in the project you've specified.\nHere you can view the video of the test, and review the logs.\n\nThere are 2 main ways to use this functionality:\n\n-  The Shell script\n-  Change the web driver used in the tests\n\nBrowserStack configuration information is found in `features/support/config_browserstack.rb`.\n\n### BrowserStack shell script\nThe `run_browserstack.sh` shell script will run all scenarios tagged with `@browser` against all the browser configurations\nlisted in the script. See `/browser_configs` for more details.\n\nIt will also out put a `report_[config_name].json` file for each run configuration, which can be used to determine pass/fails.\n\nThe script can be called with:\n```shell\nrun skeleton-acceptance-tests ./run_browserstack.sh\n```\n\nIt's aimed to provide a simple way to run tagged scenarios through different configurations.\n\n### Change the default webdriver\nThe `DRIVER` environment variable is referred to by the Capybara configuration in `features/support/config.rb`.\nThe default value is `chrome`, which will use the headless chrome configuration( `:chrome`) provided with the skeleton.\n\nTo change this default, change your Dockerfile entry to read `ENV DRIVER 'browserstack'`, and rebuild the container.\nThis will use the driver `:browserstack` configuration in `features/support/config_browserstack.rb`.\nIf you want to change browser configurations you will need to amend `BS_CONFIG` to another file from the `/browser_configs` folder too.\n\nYou can now run tests against BrowserStack remote devices using the standard `acctest` alias.\n\nExample\n```shell\n# Dockerfile changes\nENV DRIVER 'browserstack'\nENV BS_PROJECT 'Skeleton'\nENV BS_BUILD '001'\nENV BS_CONFIG 'mac_safari12'\n\n# rebuild container to apply changes\nrebuild skeleton-acceptance-tests\n\n# Run my tests against browserstack\nacctest skeleton-acceptance-tests --tags @safari_example\nConsole  messages ...\n```\n\nThe test run results will be shown in `report.json` as usual.\nThe BrowserStack dashboard will show the test run under the `Skeleton` project.\nAll scenarios tagged with `@safari_example` will have run against `browser_configs/macos_safari12.config.yml`\n\n\n## Universal dev-env support\n\nProvided via configuration.yml, Dockerfile and fragments/docker-compose-fragment.yml.\nconfiguration.yml lists the commodities the dev env needs to spin. NGINX may be used for the applications\nThe docker-compose-fragment.yml contains the service definition. The names will need modifying.\nThe Dockerfile simply sets the APP_NAME environment variable and installs the dependencies. Any specific variables or commands can be added here.\n\n## support/env.rb file\n\nThis file contains the global variables that are obtained from the environment variables specified in the Dockerfile or exported from Jenkins\n\n## support/config.rb\n\nThis details the configuration of ruby. Any libraries used must be required here. If function libraries are added to the lib-rb folder then the relative path must be added here\n\n[1]: https://www.ruby-lang.org/en\n[2]: https://www.seleniumhq.org/projects/webdriver/\n[3]: https://github.com/LandRegistry/common-dev-env\n[4]: https://github.com/rubocop-hq/ruby-style-guide\n[5]: https://github.com/LandRegistry/docker-base-images/blob/master/dev_base_ruby/4.1/Dockerfile\n[6]: https://github.com/teamcapybara/capybara\n[7]: http://chromedriver.chromium.org/\n[8]: https://cucumber.io/docs\n[9]: https://github.com/aaronFlynn/acctest-dev-env-config\n[10]: https://automation-training.herokuapp.com/\n[11]: https://govuk-prototype-kit.herokuapp.com/docs\n[12]: https://github.com/flynnbops/automation-training\n[13]: https://github.com/LandRegistry/skeleton-acceptance-tests/wiki\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandregistry%2Fskeleton-acceptance-tests","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flandregistry%2Fskeleton-acceptance-tests","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flandregistry%2Fskeleton-acceptance-tests/lists"}