{"id":17403689,"url":"https://github.com/link89/selenium-federation","last_synced_at":"2025-10-15T09:10:09.311Z","repository":{"id":37957941,"uuid":"317586904","full_name":"link89/selenium-federation","owner":"link89","description":"A cross-platform Selenium compatible testing solution that support browsers, electron apps and native apps automation for Desktop environment.","archived":false,"fork":false,"pushed_at":"2024-03-16T22:45:50.000Z","size":3376,"stargazers_count":7,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T00:04:51.540Z","etag":null,"topics":["automation","selenium","webdriver"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/link89.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-01T15:37:04.000Z","updated_at":"2023-03-18T13:25:13.000Z","dependencies_parsed_at":"2023-02-14T08:50:30.292Z","dependency_job_id":"d3503d98-259e-4bf2-a8ea-af8817d9774f","html_url":"https://github.com/link89/selenium-federation","commit_stats":{"total_commits":433,"total_committers":4,"mean_commits":108.25,"dds":0.08314087759815247,"last_synced_commit":"72afd8c79eb40cae03cf773faa95b0192ad6381d"},"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/link89%2Fselenium-federation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/link89%2Fselenium-federation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/link89%2Fselenium-federation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/link89%2Fselenium-federation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/link89","download_url":"https://codeload.github.com/link89/selenium-federation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248610359,"owners_count":21132924,"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":["automation","selenium","webdriver"],"created_at":"2024-10-16T19:06:44.427Z","updated_at":"2025-10-15T09:10:04.292Z","avatar_url":"https://github.com/link89.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Selenium Federation\n\n## Introduction\n`selenium-federation` is a cross-platform Selenium compatible testing solution that support browsers, electron apps and native apps automation for Desktop environment.\n\n### Key Fetures\n* Easy to setup.\n* Compatible with Selenium Webdriver protocol.\n* Support CDP proxy (compatible with `selenium-grid v4`'s).\n* Compatible with popular test tools/frameworks like `webdriver.io`, `testcafe`, `puppeteer`, `playwright` etc.\n* Support `ansible` style auto provisioning tasks.\n* Support native apps automation via `auto-cmd`.\n* Clean user-data automatically which allow you to run test for a long time without rebooting your machine.\n\n### Applicable scene\n* You are in a development team that need to maintain a medium scale (less than 50 devices) test infrustructure by yourself.\n* Your tests need to be executed on different OS and browsers.\n* You have electron apps or native apps to test.\n* You are a hacker that want to make your hands dirty to do something cool.\n\nIf those are not your cases, then you may consider other tools that implement the Selenium protocol.\n\n### Alternatives\n* If you are finding a zero configuraion tool, you should try [webdriver-manager](https://github.com/angular/webdriver-manager) or [selenium-standalone](https://github.com/vvo/selenium-standalone).\n* You should use `selenium-grid` or `selenoid` if \n  * You are to setup an enterprise scale cluster that gonna to be used by multiple project teams.\n  * You only have web apps to test.\n  * You have mobile apps to test.\n\n## Quick Setup\n\n### Installation\n\n```bash\nnpm install -g selenium-federation pm2 npm  # upgrade npm to avoid some wired issue\n\n# Run the following command to read manuals\nselenium-federation -h\nsf-pm2-start -h\nsf-test -h\n```\n\n### Run Service in Foreground\n\nYou can use the following command to start `selenium-federation` in foreground. It's suggested to create a dedicated workspace to run the service, as it may create some folders and download resources to the current working directory.\n\n```bash\n# Create workspace\nmkdir sf-workspace\ncd sf-workspace\n\n# For Windows \nselenium-federation -c https://raw.githubusercontent.com/link89/selenium-federation/main/examples/sample-win-local-config.yaml \n\n# For Mac OSX\nselenium-federation -c https://raw.githubusercontent.com/link89/selenium-federation/main/examples/sample-mac-local-config.yaml \n```\n\n`selenium-federation` only have one option to load configuration from local file or remote URL. All configuration options can be found in [full-config-example](/examples/full-config-example.yaml).\n\nAnd now your can run test on it with your favorite framework with the url `http://localhost:4444/wd/hub`. The base url `/wd/hub` is the same as `selenium-grid`'s for the sake of compatiblity. Here is a simple example written with `webdriver.io`.\n\n```typescript\nimport { remote } from \"webdriverio\";\n\nconst opt = {\n  hostname: 'localhost',\n  port: 4444,\n  path: '/wd/hub',\n  capabilities: {\n    browserName: 'chrome',\n  }\n};\n\n(async () =\u003e {\n  const driver = await remote(opt);\n  await driver.url(`https://html5test.com/`);\n\n  await new Promise(resolve =\u003e setTimeout(resolve, 5e3));\n  await driver.deleteSession();\n})();\n```\n\nAnother way to verify the setup is to run the `sf-test` command,\n\n```bash\nsf-test --sf-url http://localhost:4444 \n```\n\n### Run service in background with pm2\n\nForeground run is good for local debug as it prints logs in screen directly. But if you are to setup a test infrusturcture that will run for a long time, we provide another command to run service in `pm2`.\n\n```bash\n# Do forget to create workspace\nmkdir sf-workspace\ncd sf-workspace\n\n# Run service in pm2\nsf-pm2-start --name sf-local-01 -c local-config.yaml \n\n# check service status in pm2\npm2 ps\n```\n\nCompare with the previous example, everything is the same except a requirement field `--name` to specify an app name in the `pm2`. If you want to set more `pm2 start` options, you can pass them after `--`, for example\n\n```bash\nsf-pm2-start --name sf-local-01 -c local-config.yaml -- --restart-delay=3000\n```\n\n### Start hub service\n\nTo start a hub service is very simple, here is a typeical configuration of hub.\n```yaml\nrole: hub\nhost: 0.0.0.0\nport: 4444\n\nfileServer: \n  root: .\n```\nHere we also start a `fileServer` with the hub node, you can access the file service via http://localhost:4444/fs/\n\n### Use Provision Task to Download Webdriver Binary\n\n`provision task` is one of the key features of `selenium-federation` to simplify the system provision. It's inspired by `ansible`.  The most common use case is to download webdriver binary automatically. For example,\n\n```yaml\n\nprovision:\n  tasks:\n    - download: https://registry.npmmirror.com/-/binary/chromedriver/101.0.4951.41/chromedriver_win32.zip\n      cmds:\n        - powershell Expand-Archive {download_file_path} -Force -DestinationPath .  # unpack to workspace\n\n    - download: https://repo.huaweicloud.com/geckodriver/v0.31.0/geckodriver-v0.31.0-win64.zip\n      cmds:\n        - powershell Expand-Archive {download_file_path} -Force -DestinationPath .\n\n    - neverSkip: true\n      cmds:\n        - npm outdated -g selenium-federation || ( npm install -g selenium-federation \u0026\u0026 throw_error_to_restart )\n```\n\nHere we define 2 tasks to download webdirver binary for `Chrome` and `Firefox`.\nAnd the last task is use to upgrade selenium-federation automatically.\n\nYou can also run ad-hoc provision task via `/provision` endpoint, for example:\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" \\\n  -d '{\"cmds\":[\"unzip -o {download_file_path}\"],\"download\":\"https://msedgedriver.azureedge.net/102.0.1249.0/edgedriver_mac64.zip\"}' \\\n  http://127.0.0.1:4444/provision\n```\n\nPlease note that `neverSkip` will always be true when running task via API.\n\nMore example could be found in [provision-task-gallery](/examples/provision-tasks-gallery.yaml).\n\n### Termiate Service From Remote\n\nYou can access the page `http://localhost:4444/termiate` to terminate the `selenium-federation` from remote. This is useful when using with `pm2`. For example, you may change the configuration file (which is also in remote) and terminate the current process. `pm2` will bring up the service automatically afterward with the latest configuration.\n\n## Test Execution\n\n`selenium-federation` tries to keep compatible with Selenium and you can just run your existed Selenium test scripts on it. Besides of this, it provides some extra features to make it more powerful.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flink89%2Fselenium-federation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flink89%2Fselenium-federation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flink89%2Fselenium-federation/lists"}