{"id":13463258,"url":"https://github.com/jfirebaugh/konacha","last_synced_at":"2025-05-14T21:06:25.681Z","repository":{"id":2449024,"uuid":"3419782","full_name":"jfirebaugh/konacha","owner":"jfirebaugh","description":"Test your Rails application's JavaScript with the mocha test framework and chai assertion library","archived":false,"fork":false,"pushed_at":"2019-03-16T00:10:57.000Z","size":1018,"stargazers_count":1047,"open_issues_count":21,"forks_count":116,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-13T17:46:47.667Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"krasimir/lsbridge","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jfirebaugh.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","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":"2012-02-12T03:19:24.000Z","updated_at":"2025-02-14T15:50:13.000Z","dependencies_parsed_at":"2022-08-20T12:11:18.731Z","dependency_job_id":null,"html_url":"https://github.com/jfirebaugh/konacha","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfirebaugh%2Fkonacha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfirebaugh%2Fkonacha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfirebaugh%2Fkonacha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfirebaugh%2Fkonacha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jfirebaugh","download_url":"https://codeload.github.com/jfirebaugh/konacha/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227611,"owners_count":22035669,"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":[],"created_at":"2024-07-31T13:00:49.149Z","updated_at":"2025-05-14T21:06:20.657Z","avatar_url":"https://github.com/jfirebaugh.png","language":"Ruby","readme":"# Konacha\n\n[![Build Status](https://secure.travis-ci.org/jfirebaugh/konacha.png?branch=master)](http://travis-ci.org/jfirebaugh/konacha)\n[![Dependency Status](https://gemnasium.com/jfirebaugh/konacha.png)](https://gemnasium.com/jfirebaugh/konacha)\n\nKonacha ([koh-NAH-cha], a type of green tea) is a Rails engine that allows you to test your JavaScript with the\n[Mocha](http://mochajs.org/) test framework and [chai](http://chaijs.com/)\nassertion library.\n\n[![Konacha in action][2]][1]\n\n  [1]: http://www.youtube.com/watch?v=heK78M6Ql9Q\n  [2]: https://github.com/jfirebaugh/konacha/raw/master/images/youtube.png\n\nIt is similar to [Jasmine](https://github.com/pivotal/jasmine-gem) and\n[Evergreen](https://github.com/jnicklas/evergreen), but does not attempt to be framework\nagnostic. By sticking with Rails, Konacha can take full advantage of features such as\nthe asset pipeline and engines.\n\n## Installation\n\nAdd konacha to the `:test` and `:development` groups in the Gemfile and `bundle install`:\n\n```ruby\ngroup :test, :development do\n  gem 'konacha'\nend\n```\n\n## Usage\n\nCreate a `spec/javascripts` directory and name the files in it with a `_spec`\n(or `_test`) suffix. You can write the specs in either JavaScript or\nCoffeeScript, using a `.js` or `.js.coffee` extension respectively, like you\nwould any other script asset.\n\nRequire the assets under test and any other dependencies using Sprockets directives.\nFor example, suppose you wanted to test your cool JavaScript `Array#sum` method, which\nyou placed in `app/assets/javascripts/array_sum.js`. Write the specs in JavaScript in\nthe file `spec/javascripts/array_sum_spec.js`:\n\n```javascript\n//= require array_sum\n\ndescribe(\"Array#sum\", function() {\n  it(\"returns 0 when the Array is empty\", function() {\n    [].sum().should.equal(0);\n  });\n\n  it(\"returns the sum of numeric elements\", function() {\n    [1,2,3].sum().should.equal(6);\n  });\n});\n```\n\nOr, if you prefer CoffeeScript, in `spec/javascripts/array_sum_spec.js.coffee`:\n\n```coffeescript\n#= require array_sum\n\ndescribe \"Array#sum\", -\u003e\n  it \"returns 0 when the Array is empty\", -\u003e\n    [].sum().should.equal(0)\n\n  it \"returns the sum of numeric elements\", -\u003e\n    [1,2,3].sum().should.equal(6)\n```\n\nYour tests are run inside an iframe. You have the entire `\u003cbody\u003e` element to\nyourself, and it is automatically reset between tests.\n\n## Running (Rake Tasks)\n\n### In the Browser\n\nTo start a server for your tests, type:\n\n```\n$ bundle exec rake konacha:serve\n```\n\nThen open [http://localhost:3500](http://localhost:3500) in your browser, and\nyou will see all your tests running. You can also go to a sub-page to run an\nindividual spec file (e.g. `http://localhost:3500/array_sum_spec`), or a path\nto a subdirectory to run a subset of specs (e.g.\n`http://localhost:3500/models`).\n\nThis is the recommended mode for development, since you can simply hit refresh\nto reload all your test and asset files. To debug tests, use the `debugger`\nstatement anywhere in a test to halt execution.\n\nTo run code in the JavaScript console, be sure to select the desired iframe\nfirst, so your code runs in the correct context.\n\n![Selecting the test-context frame in Chrome](https://raw.github.com/jfirebaugh/konacha/master/images/frame-select.png)\n\nYou can also add the following to your `config/routes.rb` to see the specs run at `/konacha`:\n\n```ruby\nRails.application.routes.draw do\n  mount Konacha::Engine, at: \"/konacha\" if defined?(Konacha)\nend\n```\n\n### Command-Line Runner\n\nTo run your tests from the command line, type:\n\n```\n$ bundle exec rake konacha:run\n```\n\nTo run individual specs, pass a comma separated list of spec file names via\nthe `SPEC` environment variable.\n\n```\n$ bundle exec rake konacha:run SPEC=foo_spec\n$ bundle exec rake konacha:run SPEC=foo_spec,bar_spec,etc_spec\n```\n\nKonacha includes a default formatter modeled upon RSpec's ProgressFormatter.\nAdditionally, Konacha's runner implements the same protocol as RSpec, so many\nRSpec formatters also work with Konacha.\n\nTo specify one or more formatters, provide a comma separated list of class names\nin the `FORMAT` environment variable. For example, you can run both Ruby and JavaScript\nspecs with CI integration using [ci_reporter](https://github.com/nicksieger/ci_reporter):\n\n```\n$ bundle exec rake ci:setup:rspec spec konacha:run FORMAT=CI::Reporter::RSpec\n```\n\nYou will need to `require` any formatters you use. It's a good idea to do this\nwithin a `defined?` check in your [Konacha initializer](#configuration).\n\nTo automatically trigger reruns when files change, try [guard-konacha](https://github.com/alexgb/guard-konacha).\n\n## Spec Helper\n\nSince Konacha integrates with the asset pipeline, using setup helpers in your specs is\neasy. Just create a `spec_helper.js` or `spec_helper.js.coffee` file in `spec/javascripts`\nand require it in your tests:\n\n```javascript\n//= require spec_helper\n//= require array_sum\n\ndescribe(\"Array#sum\", function() {\n  ...\n});\n```\n\nThe `spec_helper` is a good place to set Mocha and Chai options as well, for instance:\n\n```javascript\n// set the Mocha test interface\n// see http://mochajs.org/#interfaces\nmocha.ui('bdd');\n\n// ignore the following globals during leak detection\nmocha.globals(['YUI']);\n\n// or, ignore all leaks\nmocha.ignoreLeaks();\n\n// set slow test timeout in ms\nmocha.timeout(5);\n\n// Show stack trace on failing assertion.\nchai.config.includeStack = true;\n```\n\n## Directives and Asset Bundling\n\nWe suggest that you explicitly require just the assets necessary for each spec.\nKonacha runs each spec file in isolation, and requiring things explicitly will help\nensure your scripts don't accumulate hidden dependencies and tight coupling.\n\nHowever, you are free to ignore this advice and require the entire application.js asset\nbundle in your specs or spec helper, or a bundled subset of assets. Requiring bundled\nassets works like it does in Rails development mode -- Konacha will detect the complete\nset of dependencies and generate a separate script tag for each one. You won't have to\nsearch through a many thousand line application.js bundle to debug a spec failure.\n\n## Configuration\n\nKonacha can be configured in an initializer, e.g. `config/initializers/konacha.rb`:\n\n```ruby\nKonacha.configure do |config|\n  config.spec_dir     = \"spec/javascripts\"\n  config.spec_matcher = /_spec\\.|_test\\./\n  config.stylesheets  = %w(application)\n  config.driver       = :selenium\nend if defined?(Konacha)\n```\n\nThe `defined?` check is necessary to avoid a dependency on Konacha in the production\nenvironment.\n\nThe `spec_dir` option tells Konacha where to find JavaScript specs.  `spec_matcher`\nis an object responding to `===` (most likely a `Regexp`); it receives a filename\nand should return true if the file is a spec. The `stylesheets` option sets the\nstylesheets to be linked from the `\u003chead\u003e` of the test runner iframe. `driver`\nnames a Capybara driver used for the `run` task. The values above are the defaults.\n\nFor [PhantomJS](https://github.com/jonleighton/poltergeist#installing-phantomjs)\nsupport you can use the [poltergeist](https://github.com/jonleighton/poltergeist)\ndriver. Require capybara/poltergeist in the configure block:\n\n```ruby\nKonacha.configure do |config|\n  require 'capybara/poltergeist'\n  config.driver = :poltergeist\nend if defined?(Konacha)\n```\n\n## Test Interface and Assertions\n\nKonacha includes a vendored copy of mocha.js and the [chai](http://chaijs.com/)\nassertion libraries. By default, it configures Mocha to use the \"BDD\" test\ninterface, which provides `describe()`, `it()`, `before()`, `after()`,\n`beforeEach()`, and `afterEach()`.\n\nKonacha will make all three of chai's assertion styles available to you: `expect`,\n`should`, and `assert`. See the chai documentation for the details.\n\nIf you use jQuery, you may want to check out [chai-jquery](https://github.com/jfirebaugh/chai-jquery)\nfor some jQuery-specific assertions. There are a lot of interesting chai\nmatchers out there, see [the chai plugins page](http://chaijs.com/plugins)\n\nTo make all these available for your konacha environment, see the\n[Konacha-chai-matchers gem](https://github.com/matthijsgroen/konacha-chai-matchers)\n\n## Templates / Fixtures\n\nKonacha has no template (a.k.a. HTML fixture) support of its own. Instead, we suggest you use\nSprocket's built in support for JavaScript template (`.jst`) files. Add a `spec/javascripts/templates`\ndirectory, place template files there (using any JS template language supported by Sprockets),\nrequire them in your spec or spec_helper, and render them into the `\u003cbody\u003e`.\n\nThe following example uses EJS. You can use an alternative templating language, like ECO, but you need to add something to your Gemfile in order for Sprokets to define the JST function and make your templates available.\n\n```ruby\ngroup :development, :test do\n  gem \"ejs\"\nend\n```\n\nFor example, in `spec/javascripts/templates/hello.jst.ejs`:\n\n```html\n\u003ch1\u003eHello Konacha!\u003c/h1\u003e\n```\n\nIn `spec_helper.js`:\n\n```javascript\n//= require_tree ./templates\n```\n\nAnd your spec:\n\n```javascript\n//= require spec_helper\n\ndescribe(\"templating\", function() {\n  it(\"is built in to Sprockets\", function() {\n    $('body').html(JST['templates/hello']());\n    $('body h1').text().should.equal('Hello Konacha!');\n  });\n});\n```\n\n## Upgrading from Konacha 3.x\n\nThe only backward-incompatible change in Konacha 4.0 is that Rails versions\nless than 4.1 are longer supported. Please upgrade to 4.1 or later.\n\n## Contributing\n\n```bash\ngit clone git://github.com/jfirebaugh/konacha.git\n```\n\nRun `bundle exec rake` to run the test suite.\n\n### Contributing to Mocha and Chai\n\nThe Konacha repository includes the\n[Mocha](https://github.com/mochajs/mocha) and\n[Chai](https://github.com/chaijs/chai) repositories as submodules, so\nyou can hack on them directly:\n\n```bash\ncd mocha # or: cd chai\ngit checkout master\n... hack-hack-hack ...\nbundle exec rake assets # make and cp assets based on your changes\n```\n\nAssuming your app's Gemfile points at your Konacha checkout (`gem 'konacha',\n:path =\u003e '~/path/to/konacha'`), your changes to Mocha and Chai are live in\nlocalhost:3500 when you refresh your browser.\n\nYou can send pull requests to Mocha and Chai straight out of your submodules.\n\n## See Also\n\nPrior art:\n\n* [Jasmine](https://github.com/pivotal/jasmine-gem)\n* [Evergreen](https://github.com/jnicklas/evergreen)\n\nSimilar projects:\n\n* [Teaspoon](https://github.com/modeset/teaspoon)\n","funding_links":[],"categories":["JavaScript","Ruby","Testing"],"sub_categories":["JavaScript Testing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfirebaugh%2Fkonacha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfirebaugh%2Fkonacha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfirebaugh%2Fkonacha/lists"}