{"id":19319896,"url":"https://github.com/vazco/meteor-universe-e2e","last_synced_at":"2025-04-22T17:32:33.154Z","repository":{"id":45947078,"uuid":"74468300","full_name":"vazco/meteor-universe-e2e","owner":"vazco","description":"Complete end-to-end/acceptance testing solution for Meteor based on Mocha \u0026 Puppeteer","archived":false,"fork":false,"pushed_at":"2021-11-25T13:19:02.000Z","size":50,"stargazers_count":15,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-13T18:25:49.435Z","etag":null,"topics":["meteor","mocha","selenium","testing","webdriverio"],"latest_commit_sha":null,"homepage":"https://atmospherejs.com/universe/e2e","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/vazco.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":"2016-11-22T12:01:06.000Z","updated_at":"2023-12-11T08:14:27.000Z","dependencies_parsed_at":"2022-09-23T09:23:09.338Z","dependency_job_id":null,"html_url":"https://github.com/vazco/meteor-universe-e2e","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vazco%2Fmeteor-universe-e2e","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vazco%2Fmeteor-universe-e2e/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vazco%2Fmeteor-universe-e2e/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vazco%2Fmeteor-universe-e2e/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vazco","download_url":"https://codeload.github.com/vazco/meteor-universe-e2e/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223902298,"owners_count":17222348,"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":["meteor","mocha","selenium","testing","webdriverio"],"created_at":"2024-11-10T01:25:45.420Z","updated_at":"2024-11-10T01:25:46.700Z","avatar_url":"https://github.com/vazco.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vazco / Universe E2E ![vazco-package-blue.svg](https://img.shields.io/badge/vazco-package-blue.svg?logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAABmJLR0QA%2FwD%2FAP%2BgvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH4QMfFAIRHb8WQgAAAY1JREFUKM%2BNkLFrGgEUxr87FMnpnXdIqxi1Q3VxachgSbcOgRBCTMbgH9CCW%2BjSUminSpEmBEIpHW7rkCmQSSjEKVOGEAK5bOFyk4c5TMRTyZ1fl5aK9ai%2F8b334%2Ft4QBBmLQmz9jpoLSKYPQCfYdaezi6atTKAMoAYgK1pJ8LkQPr5JspHsbO%2BFilAEADQArCA3Ftn%2FC40KebPO4Ln37peNNxrFxPSXTaW9cPiewDbgYkkXwBYB3B5dHES3W8cpM254ctOJhr3wsKqs7Zj%2FdOZZITkMf9yT%2FKq3e18eHf47fmTT5XE1H%2BQ3GAwDyQ%2FkkxMSvLvhP%2FxZVLc42zYJBf%2FSPMkW57nsd%2Fv03VdDgYDjkajIPkryVDIdd1Xtm0%2Fdhznptvtmr7vu5IkRRRFySiKko%2FH45BlebzgJoBdodls%2FjAM49SyrIau69etVmsIIFStVnPFYvFZoVBY1jRtJZlMpjRNm5MkCaIofhfq9XrMMIyeruuc9u1KpRIulUqqqqpLqqqW0%2Bl0OZVKyb8ANqUwunhV3dcAAAAASUVORK5CYII%3D\u0026style=flat-square)\n\nComplete end-to-end/acceptance testing solution for Meteor based on Mocha \u0026 Puppeteer\n\n*This package is currently in public beta, but we use it in production at [Vazco.eu](http://vazco.eu) with success so far.*\n\n\u003c!-- toc --\u003e\n\n- [Why?](#why)\n- [Installation](#installation)\n- [Usage](#usage)\n  * [Setting up the project](#setting-up-the-project)\n  * [Running tests in watch mode](#running-tests-in-watch-mode)\n  * [Running tests in Continuous Integration mode](#running-tests-in-continuous-integration-mode)\n    + [Usage with Bitbucket Pipelines](#usage-with-bitbucket-pipelines)\n  * [Meteor \"full application test mode\" caveats](#meteor-full-application-test-mode-caveats)\n- [Writing tests](#writing-tests)\n  * [Example test suites](#example-test-suites)\n- [Exported variables](#exported-variables)\n- [Configuration](#configuration)\n- [Batteries included](#batteries-included)\n  * [Mocha](#mocha)\n  * [Puppeteer](#puppeteer)\n- [Changelog](#changelog)\n- [License](#license)\n\n\u003c!-- tocstop --\u003e\n\n### Why?\n\nFrom [Wikipedia](https://en.wikipedia.org/wiki/End-to-end_testing):\n\n\u003e End-to-end Testing (E2E) is type of software testing used to validate different integrated components of an application by testing the flow from start to end. It also tests the behavior according to the user requirements.\n\nFrom [Meteor guide](https://guide.meteor.com/testing.html#acceptance-testing):\n\n\u003e Acceptance testing is the process of taking an unmodified version of our application and testing it from the “outside” to make sure it behaves in a way we expect. Typically if an app passes acceptance tests, we have done our job properly from a product perspective.\n\nThere is other software that would allow you to perform E2E/acceptance tests of your Meteor app (e.g. Chimp, Nightwatch, Starrynight) but we found them really cumbersome.\n\nThis package is using test drivers introduced with Meteor 1.3 and integrates more seamlessly with the whole Meteor stack.\n\nEverything is managed inside your Meteor app, so when writing test specs you can use everything you would normally use in your app.\n\n### Installation\n\n`universe:e2e` is a [test driver package](https://guide.meteor.com/testing.html#driver-packages) for Meteor.\n\nYou need to `meteor add` it to your app, but it does nothing unless you specify it while starting Meteor in test mode.\n\nAdditionally, you'll need to have [Mocha](https://mochajs.org/) and [Puppeteer](https://github.com/GoogleChrome/puppeteer) installed using npm (probably in `devDependencies`):\n\n```\nmeteor add universe:e2e\nmeteor npm install --save-dev mocha puppeteer\n```\n\nThis package won't be bundled with your production build, nor loaded during normal development (it has a `testOnly` flag).\n\n### Usage\n\n#### Setting up the project\n\nOnce the test driver and npm dependencies are installed, you need to add some setup code and write first tests.\n\nWe recommend a structure where all acceptance tests are stored inside a directory that is not loaded by default (e.g inside `imports/e2e-tests`) and only a single entry point with all imports in order is available to the app (e.g. a `main.app-tests.js` file, see caveats for more info).\n\nInside this file, you need to call a setup function as early as possible in the app lifecycle\n\n```javascript\nimport {setup} from 'meteor/universe:e2e';\n\nsetup(/** extra options go here **/)\n  .then(() =\u003e {/** test environment is ready **/})\n  .catch(() =\u003e {/** something went wrong **/});\n```\n\nFor available options check [Configuration](#configuration) section below.\n\nComplete setup for a working application can be found in the example project - [E2E Simple Todos](https://github.com/vazco/meteor-e2e-simple-todos).\n\n#### Running tests in watch mode\n\nTo run tests you need to start Meteor in [full app test mode](https://guide.meteor.com/testing.html#test-modes).\n\nExample command could look like this (you probably want to add this in [`npm scripts`](https://docs.npmjs.com/cli/run-script)):\n\n```\nmeteor test --full-app --driver-package universe:e2e --raw-logs\n```\n\nRaw logs flag is optional, but it helps with displaying test results.\n\nIn watch mode app will start and reload on any file change (either in app code or in tests).\nYou need to stop it as you would normally stop Meteor in development mode.\n\nIf you want your tests running at the same time you work on your app, you can start them on a different port (e.g. using `--port 4000` flag).\nOr work on the same instance, if dropping database data after you stop the test runner (not between Meteor restarts) is ok for you.\n\n#### Running tests in Continuous Integration mode\n\nThis package is developed to use with CI servers in mind.\n\nIn this scenario, you probably want to run the tests once and exit with code depending on tests results.\nThis could be achieved with:\n\n```\nCI=1 meteor test --full-app --driver-package universe:e2e --once --raw-logs\n```\n\nNote `--once` flag and the `CI` environment variable - it must be set to a truthy value (but it usually already is by CI providers).\n\nOtherwise, app won't stop with correct exit code when tests end.\n\n##### Usage with Bitbucket Pipelines\n\nExample of a `bitbucket-pipelines.yml` file that could be used to automate testing on the Pipelines CI.\n\n```yml\nimage: vazco/meteor-pipelines\n\npipelines:\n  default:\n    - step:\n        script:\n          - meteor npm install\n          - meteor test --full-app --driver-package universe:e2e --once --raw-logs\n\n```\n\n`vazco/meteor-pipelines` is a Docker image optimized for Meteor and E2E testing, and can be used on other Continuous Integration systems, if you don't mind the name :)\n\n#### Meteor \"full application test mode\" caveats\n\nMeteor in this mode will start your application as it normally would (but with empty DB after each start, it keeps DB data during restarts in watch mode).\n\nIt will also load files matching `*.app-test[s].*` and `*.app-spec[s].*`, e.g. `my-test.app-tests.js`, so we will put our testing code over there.\n\n`Meteor.isE2E` flag is set to `true` (useful if you want to distinguish between tests made for this package and for some other test driver)\n\n### Writing tests\n\nTests can be written like regular Mocha test suites, the only difference is that API like `describe` or `it` must be imported from `meteor/universe:e2e` atmosphere package.\n\nInside the test cases, you can use Puppeteer API (with exported `browser` and `page` objects) to manipulate the browser and simulate user behavior.\nYou can spawn new browser instances and pages (tabs) if test cases require such action.\n\nAt any point, you can use extra libraries like `chai`, `faker` or even any function from your codebase - the tests are running INSIDE the Meteor app (server side) so you can do anything you are able to do inside Meteor project. One example could be database reset or fixtures right inside Mocha's `before` callback. Possibilities are limitless.\n\n#### Example test suites\n\n```javascript\nimport {describe, it, page, setValue} from 'meteor/universe:e2e';\nimport {expect} from 'chai';\nimport faker from 'faker';\n\ndescribe('Registration', () =\u003e {\n    /* ... */\n    it('should fill and send register form', async () =\u003e {\n        // Generate random username and password\n        const password = faker.internet.password();\n        const username = faker.internet.userName();\n\n        // Fill form and submit using Puppeteer API\n        await page.type('#login-username', username);\n        await page.type('#login-password', password);\n        await page.type('#login-password-again', password);\n        await page.click('#login-buttons-password');\n    });\n\n    it('should be logged in after registration', async () =\u003e {\n        // Execute function in the browser context\n        await page.waitFor(() =\u003e Meteor.user() !== null, {timeout: 2000});\n    });\n    /* ... */\n});\n\ndescribe('Tasks', () =\u003e {\n    it('should have new task input', async () =\u003e {\n        await page.waitFor('form.new-task input', {timeout: 1000});\n    });\n\n    it('should be possible to add new task', async () =\u003e {\n        const text = faker.lorem.sentence();\n\n        // Insert text into form and submit it\n        await setValue({page}, 'form.new-task input', text);\n        await page.keyboard.press('Enter');\n\n        // Check (using XPath as an example) if a new task with this text will show up\n        await page.waitForXPath(`//span[@data-test='task-text'][contains(.,'${text}')]`, {timeout: 1000});\n    });\n\n    it('should be marked as private', async () =\u003e {\n        // Get first task handle\n        const task = await page.$('[data-test=\"task-item\"]:nth-child(1)');\n\n        // There should not be a class name\n        expect(await page.evaluate(task =\u003e task.className, task)).to.equal('');\n\n        // Click button and mark as private\n        await task.$('button.toggle-private').then(el =\u003e el.click());\n\n        // There should be a private class right now\n        expect(await page.evaluate(task =\u003e task.className, task)).to.equal('private');\n\n        // Cleanup task reference\n        await task.dispose();\n    });\n});\n```\n\nMore use cases like this can be found in the example project - [E2E Simple Todos](https://github.com/vazco/meteor-e2e-simple-todos) (based on the Meteor/React tutorial)\n\n### Exported variables\n\nA complete list of public API available as functions exported **on the server side**:\n\n- Mocha API\n    - `after`\n    - `afterEach`\n    - `before`\n    - `beforeEach`\n    - `context`\n    - `describe`\n    - `it`\n    - `specify`\n    - `xcontext`\n    - `xdescribe`\n    - `xit`\n    - `xspecify`\n\n- Utilities\n    - `createBrowser` (documentation can be found at `lib/puppeteer.js`)\n    - `onTest`\n    - `onInterrupt`\n\n- Puppeteer helpers (new helpers will be added over time, PR are welcome)\n    - `resizeWindow`\n    - `setValue`\n\nHelpers' code and documentation can be found inside `helpers/` directory.\n\n### Configuration\n\nSome parts could be configured to better suit your needs.\n\nYour custom configuration can be provided to the `setup` method.\n\nExample config could look like this:\n\n```js\nimport {setup} from 'meteor/universe:e2e';\n\nsetup({\n    mocha: { // example customization of Mocha settings\n        reporter: 'spec',\n        timeout: 30000,\n        // ... other Mocha options, full list can be found at lib/mocha.js\n    },\n    browser: { // options passed to `createBrowser`\n        isCI: false, // force environment default, leave this out for auto-detection\n        createDefaultBrowser: true, // set to false to prevent browser creation and call `createBrowser` on your own\n        launchOptions: { // options passed to Puppeteer launch settings\n            slowMo: 50\n            // ... full list can be found at https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions\n        }\n    }\n});\n```\n\nAll keys are optional, you can just call `setup()` and use sane defaults.\n\n### Batteries included\n\nThis package intention is to give everything required to write acceptance tests from within the Meteor app.\n\nBelow you find quick info about the software we use to make this package work for you out of the box.\n\nIf you need any extra libs/helpers (`chai`, `faker` etc.) you can import them from npm as you would normally do in a Meteor app.\n\n#### Mocha\n\n\u003e Mocha is a feature-rich JavaScript test framework, making asynchronous testing simple and fun. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases.\n\nMocha is used to run all test suites in `universe:e2e`.\n\nIf you want some test to be executed, you better have it inside `describe`/`it` block.\n\nDocs can be found at [mochajs.org](https://mochajs.org/)\n\nIf you want to set custom reporter etc. you can provide options under the `mocha` section of our config.\nList of available options can be found in [Mocha Wiki](https://github.com/mochajs/mocha/wiki/Using-mocha-programmatically#set-options).\nPlease note that only `ui` supported at the moment is `tdd`. If you want to use `bdd` please let us know with your use case.\n\n#### Puppeteer\n\n\u003e Puppeteer is a library which provides a high-level API to control headless Chrome. It can also be configured to use full (non-headless) Chrome. Most things that you can do manually in the browser can be done using Puppeteer.\n\nPuppeteer is used for browser automation, unlike most E2E test runners, which are based on Selenium.\nOur solution is more powerful but limited to only one browser family (Chromium and Chrome).\nDepending on your case this may or may not be an issue for you.\n\nPuppeteer API should be familiar to people using other browser testing frameworks.\nUniverse E2E creates an instance of Puppeteer's `browser` an `page` for you, so you can them to manipulate spawned browser with Puppeteer's API.\n\nUniverse E2E v0.2 and earlier was based on Selenium and WebDriverIO, so [you can check it out](https://github.com/vazco/meteor-universe-e2e/tree/v0.2.0) if your looking for such solution, but we're not providing support for it anymore.\n\n### Changelog\n\nVersion history can be found at [releases page](https://github.com/vazco/meteor-universe-e2e/releases).\n\n### License\n\n\u003cimg src=\"https://vazco.eu/banner.png\" align=\"right\"\u003e\n\n**Like every package maintained by [Vazco](https://vazco.eu/), Universe E2E is [MIT licensed](https://github.com/vazco/uniforms/blob/master/LICENSE).**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvazco%2Fmeteor-universe-e2e","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvazco%2Fmeteor-universe-e2e","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvazco%2Fmeteor-universe-e2e/lists"}