{"id":19418015,"url":"https://github.com/americanexpress/busybee","last_synced_at":"2025-04-24T13:34:24.484Z","repository":{"id":44999134,"uuid":"209110246","full_name":"americanexpress/busybee","owner":"americanexpress","description":"BusyBee is an alternative API for IdlingResources in Espresso tests","archived":false,"fork":false,"pushed_at":"2023-01-06T15:38:23.000Z","size":203,"stargazers_count":185,"open_issues_count":9,"forks_count":9,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-14T13:05:23.855Z","etag":null,"topics":["android","espresso","testing-library"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/americanexpress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-17T16:57:41.000Z","updated_at":"2024-01-28T16:07:44.000Z","dependencies_parsed_at":"2023-02-06T06:02:19.564Z","dependency_job_id":null,"html_url":"https://github.com/americanexpress/busybee","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Fbusybee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Fbusybee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Fbusybee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Fbusybee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/americanexpress","download_url":"https://codeload.github.com/americanexpress/busybee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223954770,"owners_count":17231189,"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":["android","espresso","testing-library"],"created_at":"2024-11-10T13:12:25.215Z","updated_at":"2024-11-10T13:12:26.227Z","avatar_url":"https://github.com/americanexpress.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BusyBee - Tell Espresso when it needs to be patient because your app is busy 🐝\n\n\u003cimg src=\"images/busybee.png\" width=100\u003e\n\nBusyBee is an alternative API for [IdlingResource][]s in [Espresso][] tests. You can use BusyBee instead of\n[CountingIdlingResource][] to get better log messages and improve your ability to debug problems related to\n[IdlingResource][]s.\n\nBusyBee is meant to be used with [Espresso][]. You use BusyBee inside the \"app under test\". It allows the \"app under\ntest\" to tell Espresso when it is `busyWith` an operation and, conversely, allows the app to tell Espresso when the\noperation is `completed`. Tracking `busyWith`/`completed` helps your **Espresso tests be fast and reliable**.\n\nIf you write [Espresso][] tests, proper use of the [IdlingResource][] API is critical for ensuring that your tests are\nfast and reliable. IdlingResource can be hard to use correctly and it can be hard to understand what is happening with\nyour IdlingResources when you are debugging problems with your tests. That is where BusyBee comes in.\n\n## Comparison with [CountingIdlingResource][]\n\nIn some ways, BusyBee is similar to [CountingIdlingResource][], but it does have some notable advantages:\n\n- Rather than track only the _number_ of operations in progress, BusyBee keeps track of the set of operations currently\n  in progress. In progress operations are represented by a Java object, which could be a string, request object, etc.\n  This allows for easier debugging, as it allows you to inspect the set of in progress operations across the whole app.\n- When Espresso times out because the app is busy, your logs can show the list of in progress operations.\n- BusyBee lets you separately enable/disable tracking of specific categories of operations (e.g. `NETWORK` operations)\n- The `BusyBee#completed(thing)` method is idempotent (`CountingIdlingResource#decrement` is not). This is useful when\n  you have unreliable/multiple signals (e.g. WebView) to tell you that an operation has completed. Also, you can\n  `completed(thing)` even if you never were `busyWith(thing)`\n\n**Trade-off:** While there are a number of advantages listed above, the downside of `BusyBee` (and\n`CountingIdlingResource`) is that you are modifying your app under test for purely testing purposes.\n\n# How to use BusyBee\n\nInclude the BusyBee dependencies in your `build.gradle` files. When tests are not running, the **no-op** implementation\nis automatically used to minimize overhead of BusyBee (since it is only needed during tests).\n\n[Find the latest version on Maven Central](https://search.maven.org/artifact/io.americanexpress.busybee/busybee-core)\n\n_Required_: For Android modules:\n\n```gradle\n    implementation 'io.americanexpress.busybee:busybee-android:$version'\n```\n\n_Optional_: Only needed, if you want to use BusyBee in a non-Android module:\n\n```gradle\n    implementation 'io.americanexpress.busybee:busybee-core:$version'\n```\n\nBusyBee releases are available on Maven Central.\n\n```gradle\n    repositories {\n        exclusiveContent {\n            forRepository { mavenCentral() }\n            filter { includeGroup(\"io.americanexpress.busybee\") }\n        }\n    }    \n```\n\nOn each merge to `main`, a `-SNAPSHOT` version is published to https://s01.oss.sonatype.org/content/repositories/snapshots/\n\nInside your _app_, tell `BusyBee` what operations your app is `busyWith`, and when that operation is `completed`.\n\n```java\n    class BackgroundProcessor {\n        private final BusyBee busyBee = BusyBee.singleton();\n\n        void processThing(Thing thing){\n            // Espresso will wait\n            busyBee.busyWith(thing);\n            try {\n                thing.process();\n            } finally {\n                // Espresso will continue\n                busyBee.completed(thing);\n            }\n        }\n    }\n```\n\nThat's all! Now Espresso will wait until your app is not busy before executing its actions and assertions.\n\n## Categories\n\nAssigning a `Category` to your operations is an advanced feature of `BusyBee`. By default, all operations are in the\n`GENERAL` category. But, you can also add operations in other categories such as `NETWORK`. You can toggle tracking for\nany category with `payAttentionToCategory`/`ignoreCategory`. When a category is being \"ignored\" then Espresso will not\nwait for operations in that category.\n\nFor example, you might want to perform actions on your UI or assert things about your UI while a network request is\nstill in progress. In this case, you don't want Espresso to wait for the network requests to complete, but you still\nwant Espresso to wait for other operations in your app. To accomplish this, you would use\n`busyBee.ignoreCategory(NETWORK)`, then perform actions and assertions on your UI, then call\n`busybee.payAttentionToCategory(NETWORK)` so Espresso will again wait for network operations to complete.\n\n## BusyBeeExecutorWrapper\n\nIf you have an executor and you need Espresso to know the app is \"busy\" anytime that executor is executing something,\nthen you can wrap the `Executor` with `BusyBeeExecutorWrapper`. Operations executed with the wrapped `Executor` will\ncause `BusyBee` to be \"busy\" while they are in progress.\n\n```java\n   Executor backgroundTasks;\n   Executor busyBeeBackgroundTasks =\n                         BusyBeeExecutorWrapper.with(busyBee)\n                                               .wrapExecutor(backgroundTasks)\n                                               .build();\n    busyBeeBackgroundTasks.execute(operation);\n```\n\n## Contributing\n\nWe welcome Your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source\nProject managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to\nthe terms below. Except for the rights granted in this Agreement to American Express and to recipients of software\ndistributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions.\nPlease [fill out the Agreement][].\n\n## License\n\nAny contributions made under this project will be governed by the [Apache License 2.0][].\n\nThe Android™ robot is reproduced or modified from work created and shared by Google and used according to terms\ndescribed in the Creative Commons 3.0 Attribution License. Android is a trademark of Google Inc.\n\n## Code of Conduct\n\nThis project adheres to the [American Express Community Guidelines][]. By participating, you are expected to honor these\nguidelines.\n\n[espresso]: https://developer.android.com/training/testing/espresso\n[idlingresource]: https://developer.android.com/reference/androidx/test/espresso/IdlingResource\n[countingidlingresource]: https://developer.android.com/reference/androidx/test/espresso/idling/CountingIdlingResource\n[fill out the agreement]: https://cla-assistant.io/americanexpress/busybee\n[apache license 2.0]: https://github.com/americanexpress/busybee/blob/main/LICENSE.txt\n[american express community guidelines]: https://github.com/americanexpress/busybee/blob/main/CODE_OF_CONDUCT.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Fbusybee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famericanexpress%2Fbusybee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Fbusybee/lists"}