{"id":14967392,"url":"https://github.com/godaddy/ekke","last_synced_at":"2025-06-15T15:34:55.206Z","repository":{"id":34898716,"uuid":"187255037","full_name":"godaddy/ekke","owner":"godaddy","description":"Ekke is a test runner for React-Native, it allows you to execute your test code directly on the device enabling you to test in the same environment as your production users.","archived":false,"fork":false,"pushed_at":"2024-05-26T03:51:18.000Z","size":1562,"stargazers_count":133,"open_issues_count":43,"forks_count":6,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-06-09T09:11:22.041Z","etag":null,"topics":["devtool","integration","mocha","mock","react-native","tape","testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/godaddy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-17T17:16:46.000Z","updated_at":"2025-06-05T03:36:11.000Z","dependencies_parsed_at":"2024-08-23T14:34:30.325Z","dependency_job_id":null,"html_url":"https://github.com/godaddy/ekke","commit_stats":{"total_commits":27,"total_committers":8,"mean_commits":3.375,"dds":0.6666666666666667,"last_synced_commit":"fe952a456f84d83db7578ee5a13525ef3cb391dd"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/godaddy/ekke","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fekke","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fekke/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fekke/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fekke/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godaddy","download_url":"https://codeload.github.com/godaddy/ekke/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fekke/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259998034,"owners_count":22943733,"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":["devtool","integration","mocha","mock","react-native","tape","testing"],"created_at":"2024-09-24T13:37:59.469Z","updated_at":"2025-06-15T15:34:55.180Z","avatar_url":"https://github.com/godaddy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `EKKE`\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/godaddy/ekke.svg)](https://greenkeeper.io/)\n\n#### [Ekke-Ekke-Ekke-Ekke][NI] PTANG Zoo Boing! Z' nourrwringmm[...][Ekke]\n\n`ekke` a unique new test runner for React-Native. Unlike other testing\nframeworks, it doesn't execute your tests in Node.js, with a bunch of mocks, but\ninstead, it orchestrates the bundling and execution of tests directly **inside\nyour React-Native application**.  `ekke` allows your tests to fully access every\nAPI to the platform has to offer.\n\n### Why should you adopt Ekke for React-Native testing?\n\n- **Platform independent** The test runner **does not contain any native code**\n  that means that every platform that React-Native supports now, or in the\n  future will work out of the box.\n- **Code confidence** Tests run in the environment of your production code. No\n  need to rely on imperfect mocks. Tests run on devices to guarantee API's match\n  specifications.\n- **Different test runners** At its core, Ekke is nothing more than an\n  orchestration tool. We have built-in support for different test runners.\n- **Rendering** It's not just unit tests. Ekke provides a rendering API that\n  allows you to mount and render components in your test suite.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"800\" height=\"607\" src=\"https://raw.githubusercontent.com/godaddy/ekke/master/docs/ekke-react-native-intro.gif\" /\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eEkke in action: running a test suite, streaming results back to the CLI\u003c/sub\u003e\n\u003c/p\u003e\n\n## Installation\n\nThe module is released in the public NPM Registry and can be installed by running:\n\n```bash\nnpm install --save ekke\n```\n\nAfter installation, you can [integrate](#integration) `ekke` into your project.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Integration](#integration)\n- [Runners](#runners)\n  - [mocha](#mocha)\n  - [Tape](#tape)\n- [API](#API)\n  - [Component](#component)\n  - [render](#render)\n- [CLI](#cli)\n  - [run](#run)\n  - [help](#help)\n- [Debugging](#debugging)\n  - [The Ekke CLI](#the-ekke-cli)\n  - [React Native Component](#react-native-component)\n\n## Integration\n\nEkke needs a host application to run. That can either be the application you are\ncurrently developing or fresh installation of `react-native init`.\n\nNot sure what to pick?\n\n- **Application developers** Using the application that you're currently\n  developing is recommended. This allows your test suites to execute in\n  precisely the same environment. Also, it will enable your test suites to\n  leverage any `NativeModule` that your application might be consuming.\n- **Library authors** It depends on the library you're developing. If you are\n  building a native add-on, or include `NativeModules` as dependencies, it's\n  advised to create an example application in your project that has all native\n  libraries linked. TODO: What is the alternative here, if there is one?\n\nIntegrating is as easy as importing `ekke`, and including the [component] in\nyour app!\n\n```js\nimport { Ekke } from 'ekke';\n\nfunction App() {\n  return (\n    \u003c\u003e\n      \u003cEkke /\u003e\n\n      \u003cView\u003e\n        \u003cText\u003eYour App Here\u003c/Text\u003e\n      \u003c/View\u003e\n    \u003c/\u003e\n  )\n}\n```\n\nYou can now run your tests by executing the [run] command of the `ekke` CLI:\n\n```sh\n# Make sure that the simulator of your choice is running.\nreact-native run-ios # or react-native run-android\n\nekke run glob/pattern/*.test.js more/test/files.js --using mocha\n```\n\nAnd now watch the magic unfold on your app.\n\n\u003e If you are worried about shipping `Ekke` in your application, the component is\n\u003e using [process.env.NODE_ENV][env] to switch between [development][dev] and\n\u003e [production][prod] builds. Production builds will completely remove `Ekke`\n\u003e from your code. You can also conditionally include it `{ __DEV__ \u0026\u0026 \u003cEkke /\u003e }`.\n\n## Runners\n\nAt its core, Ekke is nothing more than an orchestration tool, it runs\n[Metro][metro] bundler with a specific configuration, executes code\nautomatically in the React Native environment, and reports back in the CLI. To\nrun the test, we need to know which test runner you prefer so we can bundle it\nwith the tests. The following runners are available:\n\n- [mocha](#mocha)\n- [tape](#tape)\n\n### mocha\n\nTo use [Mocha](https://mochajs.org/) make sure you have the testing framework as\nwell as an assertion framework installed in your project:\n\n```bash\nnpm install --save-dev mocha\nnpm install --save-dev assume # or any other assert framework, e.g. chai\n```\n\nOnce all your dependencies finish installing, you can start writing your tests.\n\n```js\nimport { describe, it } from 'mocha';\nimport { render } from 'ekke';\nimport assume from 'assume';\n\ndescribe('The best test suite in the world', function () {\n  it('is amazing', function () {\n    const amazing = 'amazing';\n\n    assume(amazing).is.a('string');\n    assume(!!amazing).is.true();\n  });\n});\n```\n\nProvide `mocha` as value to the `--using` flag to select it as test runner.\n\n```bash\nekke run test.js --using mocha\n```\n\nThe following Mocha options can be customized using the follow CLI flags:\n\n- `--mocha.fgrep` Only run tests containing this string.\n  **Defaults to `''`**.\n- `--mocha.grep` Only run tests matching this string.\n  **Defaults to `''`**.\n- `--mocha.invert` Inverts grep and fgrep matches.\n  **Defaults to `false`**.\n- `--mocha.ui` Specify user interface.\n  **Defaults to `bdd`**.\n- `--mocha.reporter` Specify reporter to use.\n  **Defaults to `spec`**.\n- `--mocha.slow` Specify \"slow\" test threshold (in milliseconds).\n  **Defaults to `75`**.\n- `--mocha.timeout` Specify the test timeout threshold (in milliseconds).\n  **Defaults to `2000`**.\n- `--mocha.bail` Abort (\"bail\") after first test failure.\n  **Defaults to `true`**.\n- `--mocha.color` Force-enable color output.\n  **Defaults to `true`**.\n- `--mocha.inlineDiffs` Display actual/expected differences inline within each string.\n  **Defaults to `true`**.\n\n```bash\nekke run test.js --using mocha --mocha.reporter min --mocha.timeout 5000\n```\n\n### Tape\n\nUsing [tape](https://github.com/substack/tape) as the test runner is pretty\nself-explanatory. You import `tape` into your test files and write your tests\nand assertions using provided by the framework.\n\n```js\nimport { render } from 'ekke';\nimport test from 'tape';\n\ntest('one', function (t) {\n  t.plan(2);\n  t.ok(true);\n\n  setTimeout(function () {\n    t.equal(1+3, 4);\n  }, 100);\n});\n```\n\nOnce the tests are completed, simple tell `ekke` that you're `--using tape` to\nrun the tests.\n\n```bash\nekke run test.js --using tape\n```\n\nThe will run your tests, and output the TAP (Test. Anything. Protocol) to your\nterminal which you can pipe to any of the [Pretty Tap\nReporters](https://github.com/substack/tape#pretty-reporters) that you might\nhave installed. For example, if you want to use `tap-spec`:\n\n```bash\nekke run test.js --using tape | tap-spec\n```\n\n## API\n\nThe API exposes the following methods:\n\n- [component](#component)\n- [render](#render)\n\n### Component\n\n```js\nimport { Ekke } from 'ekke';\n```\n\nThe `Ekke` component controls the orchestration, execution, and rendering of the\ntest suite. The component can be used as a wrapper, or as a regular component\nand be included in your application.\n\nThe component accepts the following **optional** properties:\n\n- `interval`, **String**, The component doesn't know when you are using the CLI,\n  so it polls at a given interval, with an HTTP request, to the server that runs\n  in the CLI to figure out if it's active and is waiting for tests to run. The\n  lower the interval, the quicker your tests will be picked up by the component,\n  but also the more performance it takes away from your app.\n  **Defaults to `10 seconds`**.\n- `hostname`, **String**, The hostname of your machine that the CLI server is\n  running on.\n  **Defaults to `localhost` on iOS and `10.0.2.2` on Android**.\n- `port`, **Number**, The port number that the CLI server is running on.\n  **Defaults to `1975`**.\n- `alive`, **Function**, Function to execute when the `Ekke` test runner is\n  activated and is about to run the test suites.\n\n```js\n//\n// Stand alone.\n//\n\u003cEkke /\u003e\n\n//\n// Or wrap your app with it, you decide what is best for your application.\n//\n\u003cEkke\u003e\n  \u003cApp /\u003e\n\u003c/Ekke\u003e\n```\n\nTo see an example of the implementation, take a look at our [index.js][index]\nfile. It's what we use to test our code.\n\n### render\n\n```js\nimport { render } from 'ekke';\n```\n\nThe render method allows you to render any React-Native component on the screen\nof the application.\n\n```js\nimport { View } from 'react-native';\nimport { render } from 'ekke';\nimport React from 'react';\n\ndescribe('test', function () {\n  it('renders a red square', function () {\n    const ref = React.createRef();\n    await render(\u003cView style={{\n      backgroundColor: 'red',\n      width: 100,\n      height: 100\n    }} ref={ ref } /\u003e);\n\n    //\n    // You can now use ref.current to access the rendered view.\n    // Not only that, but there's big red square on your app as well.\n    //\n  });\n});\n```\n\n## CLI\n\nThe `ekke` CLI is automatically installed in your `node_modules` when you\ninstall `ekke` in the project as a dependency. We use the CLI to communicate\nbetween the `\u003cEkke /\u003e` component that you included in your application and the\nterminal.\n\nThe CLI should **not be globally installed**. Instead, you directly reference\nthe locally installed binary from your `package.json`.\n\n```json\n{\n  \"name\": \"your-super-awesome-package\",\n  \"scripts\": {\n    \"test\": \"ekke run test/*.js --using mocha\"\n  }\n}\n```\n\nAnd run the scripts using `npm`.\n\n```bash\nnpm test\n\n# You can use the double dash support from npm to send additional flags:\n# npm test -- --watch\n```\n\nAlternatively, you can use the `npx` command to execute the commands as well\nwithout the requirement of global installation of `ekke`:\n\n```bash\nnpx ekke \u003ccommands here\u003e\n```\n\nThe following CLI commands are available:\n\n- [run](#run)\n- [help](#help)\n\n### run\n\n```bash\nekke run \u003cglob or files to run\u003e --flags\n```\n\nThe `run` command allows you to run your specified tests on the device that\nincluded the `\u003cEkke /\u003e` React component. When you run the command, we will\nexecute the following:\n\n- Start up the Metro bundler on the specified `hostname` and `port`.\n- Attach a WebSocket server on the created Metro bundler, for communication purposes.\n- Find all the test files you want to include based on the supplied glob.\n- Wait for the poll request from the `\u003cEkke /\u003e` component.\n- Bundle all your tests, and the specified library using Metro Bundler.\n- Listen to progress events that are sent by `\u003cEkke /\u003e` component over the\n  WebSocket connection.\n- Proxy all the `console.*`, `process.stdout` to your terminal.\n- Close the CLI again with error code `0` or `1` depending on if your tests pass.\n\nThe `run` command assumes that all CLI arguments after the `run` command are the\ntest files that need to execute inside React-Native. We allow single or multiple\nfiles, a [glob][glob] pattern, or a combination of files and globs.\n\n```bash\n# Executes test/1.js, test/2.js, and then test/2.js using the mocha runner.\nekke run test/1.js test/2.js test/3.js --using mocha\n\n# The same above, but done using a glob pattern to fetch all .js files\n# from the test directory\nekke run test/*.js --using mocha\n\n# Executes test/1.js and then all the .test.js files\nekke run test/1.js test/*.test.js --using tape\n```\n\nYou can use the following CLI flags to change the behavior of the command:\n\n- `--using {runner}` This tells Ekke which runner should be used to execute your\n  tests.\n  **Defaults to `mocha`** See [Runners](#runners) for all runners.\n- `--watch` By default, we close the process with either an exit code `0` or `1`\n  as an indication of the test results (0 passes, 1 failure). If you do not want\n  the process to exit, you can use the `--watch` flag to keep the CLI process\n  alive.\n  **Defaults to false.**\n- `--reset-cache` The Metro Bundler caching system is enabled by default so\n  that tests run in a performant way and don't always rebuild. Using this\n  flag will disable the cache.\n  **Defaults to false.**\n- `--cache-location` We already made sure that the Metro Bundler cache of your\n  test doesn't collide with your test cache, but if you like to store it\n  somewhere else you can change it with this flag.\n  **Defaults to `os.tempdir()/ekke-cache`.**\n- `--no-silent` We silence the output of the Metro bundler by default, this\n  allows you to see the Metro bundler output again.\n  **Defaults to false.**\n- `--hostname` The hostname we should attach our Metro Bundler on. The hostname\n  should be accessible by React-Native application.\n  **Defaults to `localhost`.**\n- `--port` The port number we should use for the Metro Bundler, we don't want to\n  clash with the Metro bundler of your `react-native start` command so it should\n  be different, but still accessible by your React-Native application.\n  **Defaults to `1975`** (The year Monty Python and the Holy Grail got released)\n- `--require` Files that should be required before your test suites are required\n  **Defaults to ¯\\_(ツ)_/¯, nothing**\n\nIn addition to these default flags, any flag that you prefix with the name of\nthe runner will be considered as options and used as configuration:\n\n```bash\nekke run test.js --using mocha --mocha.timeout 3000\n```\n\nSee the [Runners](#runners) for their specific configuration flags.\n\n### help\n\nDisplay a list of all the available command their supported CLI flags. The help\nmessage is visible when you run `ekke` without, an unknown, or the `help`\ncommand:\n\n```\n\nekke (v1.0.2)\nEkke-Ekke-Ekke-Ekke-PTANG. Zoo-Boing. Z' nourrwringmm...\n\nCOMMANDS:\n\nrun      Run the given glob of test files.\n         --port           Port number that Metro Bundler should use.\n         --hostname       Hostname that Metro Bundler should use.\n         --using          Name of the test runner to use.\n         --watch          Don't exit when the tests complete but keep listening.\n         --no-silent      Do not suppress the output of Metro.\n         --require        Require module (before tests are executed).\n         --reset-cache    Clear the Metro cache.\n         --cache-location Change the Metro cache location.\nhelp             Displays this help message.\n         --no-color       Disable colors in help message.\n\nEXAMPLES:\n\n$ ekke run ./test/*.test.js --using mocha\n\n```\n\nThe output contains colors by default if you wish to remove those you can use\nthe `--no-color` flag.\n\n## Debugging\n\nBoth the `CLI` and the `react-native` code bases use [diagnostics] under the\nhood for logging purposes. The logs are disabled by default but can be enabled\nby using the `DEBUG` feature flags. They both log under the `ekke:*` namespace.\n\n#### The Ekke CLI\n\n```js\nDEBUG=ekke* ekke \u003cyour command here\u003e\n```\n\n#### React Native Component\n\n```js\nimport { AsyncStorage } from 'react-native';\n\nAsyncStorage.setItem('debug', 'ekke*', function () {\n  //\n  // Reload your app, and the debug logs will now be enabled.\n  //\n});\n```\n\nFor more detailed information about [diagnostics], please see their project page.\n\n## Development\n\n- **Fork** Fork the repository to create a copy to your own GitHub account.\n- **Clone** Clone the newly created GitHub repo to your local machine.\n- **Branch** Create a fresh new branch from the master branch.\n- **Install** Run `npm install` to install dependencies and devDependencies.\n- **Setup** Run `npm run setup` to create development specific folders.\n- **Hack** Make your changes. Write tests covering your changes.\n- **Test** Run both `npm test` and `npm test:ekke` to ensure nothing got broken.\n- **Push** Commit and push your changes to fork.\n- **Pull Request** Create a pull request from your created branch to our master.\n- **Review** We'll review your change, and ask for updates if need.\n- **Merge** Virtual high fives are exchanged when your PR lands.\n\n## License\n\n[MIT](LICENSE)\n\n[diagnostics]: https://github.com/3rd-Eden/diagnostics\n[metro]: https://github.com/facebook/metro\n[NI]: https://en.wikipedia.org/wiki/Knights_Who_Say_%22Ni!%22\n[Ekke]: https://youtu.be/RZvsGdJP3ng?t=17\n[env]: ./index.js\n[dev]: ./development.js\n[prod]: ./production.js\n[component]: #component\n[run]: #run\n[index]: ./index.js\n[glob]: https://www.npmjs.com/package/glob\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fekke","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodaddy%2Fekke","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fekke/lists"}