From 0369e8c6fbb06171b8340090c970e2b2d22aba00 Mon Sep 17 00:00:00 2001 From: Yaroslav Admin Date: Mon, 12 Apr 2021 17:53:26 +0200 Subject: [PATCH] docs: updates to the documentation to support new markdown renderer (#3672) Companion PR for https://github.com/karma-runner/karma-runner.github.com/pull/62. * docs: fix invalid heading syntax It is not recognized as a heading by the markdown parser without a whitespace. * docs: fix weird syntax to reduce diff Old parser considered this the same list, but new parser assumes that these are two separate lists. Technically it should be a nested list, but it is old and shouldn't really matter. I'm doing this change to reduce the diff I need to review after switching to the new markdown parser. * docs: fix invalid markdown Items nested in the list item, must be indented 3 spaces, not 2 spaces. New parser produced a pretty messed up markup from the invalid markdown. * docs: remove redundant whitespaces in the list items --- CHANGELOG.md | 2 +- docs/about/03-migration.md | 3 +- docs/dev/01-contributing.md | 2 + docs/dev/03-maintaining.md | 4 +- docs/dev/04-public-api.md | 30 +++--- docs/dev/05-plugins.md | 2 + docs/dev/06-git-commit-msg.md | 2 + docs/index.md | 2 + docs/intro/04-faq.md | 2 + docs/intro/05-troubleshooting.md | 2 + docs/plus/01-requirejs.md | 2 + docs/plus/02-travis.md | 2 + docs/plus/03-jenkins.md | 2 + docs/plus/04-semaphore.md | 2 + docs/plus/06-angularjs.md | 2 + docs/plus/08-emberjs.md | 152 ++++++++++++++++--------------- docs/plus/09-codio.md | 2 +- docs/plus/10-teamcity.md | 2 + 18 files changed, 122 insertions(+), 95 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3bb7d4b1..831c0e981 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2121,7 +2121,7 @@ module.exports = function(karma) { #### Breaking Changes -* rename the project to "Karma": +- rename the project to "Karma": - whenever you call the "testacular" binary, change it to "karma", eg. `testacular start` becomes `karma start`. - if you rely on default name of the config file, change it to `karma.conf.js`. - if you access `__testacular__` object in the client code, change it to `__karma__`, eg. `window.__testacular__.files` becomes `window.__karma__.files`. ([026a20f7](https://github.com/karma-runner/karma/commit/026a20f7b467eb3b39c68ed509acc06e5dad58e6)) diff --git a/docs/about/03-migration.md b/docs/about/03-migration.md index 5b39ce0d8..6f542df46 100644 --- a/docs/about/03-migration.md +++ b/docs/about/03-migration.md @@ -1,5 +1,6 @@ +--- pageTitle: Migration from v0.10 - +--- The good thing is that you don't have to migrate everything at once. You can leave all the existing projects using an older version of Karma and only use the latest diff --git a/docs/dev/01-contributing.md b/docs/dev/01-contributing.md index 8cfb42aa0..d1b57244d 100644 --- a/docs/dev/01-contributing.md +++ b/docs/dev/01-contributing.md @@ -1,4 +1,6 @@ +--- pageTitle: Contributing to Karma +--- **Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub] diff --git a/docs/dev/03-maintaining.md b/docs/dev/03-maintaining.md index 62938267f..6e541ffb1 100644 --- a/docs/dev/03-maintaining.md +++ b/docs/dev/03-maintaining.md @@ -1,6 +1,6 @@ +--- pageTitle: Maintaining Karma - - +--- This document is for people working on Karma. It describes common tasks such as triaging or merging pull requests. diff --git a/docs/dev/04-public-api.md b/docs/dev/04-public-api.md index 717eb1855..095527ccd 100644 --- a/docs/dev/04-public-api.md +++ b/docs/dev/04-public-api.md @@ -6,7 +6,7 @@ You can, however, call Karma programmatically from your node module. Here is the ### `constructor` -- **Returns:** `Server` instance. +- **Returns:** `Server` instance. #### Usage @@ -150,7 +150,7 @@ This event gets triggered whenever all the browsers, which belong to a test run, ### `runner.run(options, [callback=process.exit])` -- **Returns:** `EventEmitter` +- **Returns:** `EventEmitter` The equivalent of `karma run`. @@ -310,8 +310,8 @@ cfg.parseConfig( #### `configFilePath` argument -- **Type:** String | `null` | `undefined` -- **Default Value:** `undefined` +- **Type:** String | `null` | `undefined` +- **Default Value:** `undefined` A string representing a file system path pointing to the config file whose default export is a function that will be used to set Karma configuration @@ -319,16 +319,16 @@ options. This function will be passed an instance of the `Config` class as its first argument. If this option is not provided, then only the options provided by the `cliOptions` argument will be set. -- JavaScript must use CommonJS modules. -- ECMAScript modules are not currently supported by Karma when using +- JavaScript must use CommonJS modules. +- ECMAScript modules are not currently supported by Karma when using JavaScript. - - Other formats, such as TypeScript, may support ECMAScript modules. + - Other formats, such as TypeScript, may support ECMAScript modules. #### `cliOptions` argument -- **Type:** Object | `null` | `undefined` -- **Default Value:** `undefined` +- **Type:** Object | `null` | `undefined` +- **Default Value:** `undefined` An object whose values will take priority over options set in the config file. The config object passed to function exported by the config file will already @@ -344,8 +344,8 @@ programatic users may construct this object or leave it out entirely. #### `parseOptions` argument -- **Type:** Object | `null` | `undefined` -- **Default Value:** `undefined` +- **Type:** Object | `null` | `undefined` +- **Default Value:** `undefined` `parseOptions` is an object whose properties are configuration options that allow additional control over parsing and opt-in access to new behaviors or @@ -357,8 +357,8 @@ not related to the configuration of Karma itself. ##### `parseOptions.promiseConfig` option -- **Type:** Boolean -- **Default Value:** `false` +- **Type:** Boolean +- **Default Value:** `false` When `parseOptions.promiseConfig === true`, then `parseConfig` will return a promise instead of a configuration object. @@ -382,8 +382,8 @@ disables process exiting and allows errors to result in rejected promises.**_ ##### `parseOptions.throwErrors` option -- **Type:** Boolean -- **Default Value:** `false` +- **Type:** Boolean +- **Default Value:** `false` In the past, `parseConfig()` would call `process.exit(exitCode)` when it encountered a critical failure. This meant that your own code had no way of diff --git a/docs/dev/05-plugins.md b/docs/dev/05-plugins.md index 8c0e787df..1a93773e7 100644 --- a/docs/dev/05-plugins.md +++ b/docs/dev/05-plugins.md @@ -1,4 +1,6 @@ +--- pageTitle: Developing Plugins +--- Karma can be extended through plugins. There are five kinds of plugins: *framework*, *reporter*, *launcher*, *preprocessor* and *middleware*. Each type allows to modify a certain aspect of the Karma behavior. diff --git a/docs/dev/06-git-commit-msg.md b/docs/dev/06-git-commit-msg.md index a366ebb0d..0365657bb 100644 --- a/docs/dev/06-git-commit-msg.md +++ b/docs/dev/06-git-commit-msg.md @@ -1,4 +1,6 @@ +--- showInMenu: false +--- ## The reasons for these conventions: - automatic generating of the changelog diff --git a/docs/index.md b/docs/index.md index ce24bea3d..2b040b628 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,2 +1,4 @@ +--- layout: homepage pageTitle: Spectacular Test Runner for Javascript +--- diff --git a/docs/intro/04-faq.md b/docs/intro/04-faq.md index 7317ad867..a70444f2c 100644 --- a/docs/intro/04-faq.md +++ b/docs/intro/04-faq.md @@ -1,5 +1,7 @@ +--- pageTitle: Frequently Asked Questions menuTitle: FAQ +--- The list below is a collection of common questions regarding Karma and its use. If you have any other questions in mind, please visit the [mailing list] to let the community know. diff --git a/docs/intro/05-troubleshooting.md b/docs/intro/05-troubleshooting.md index c6746b3da..89193a676 100644 --- a/docs/intro/05-troubleshooting.md +++ b/docs/intro/05-troubleshooting.md @@ -1,5 +1,7 @@ +--- pageTitle: Troubleshooting menuTitle: Troubleshooting +--- karma has an extensive set of tests and we have limited time to help with bugs. Here are some suggestions to get you unstuck. diff --git a/docs/plus/01-requirejs.md b/docs/plus/01-requirejs.md index 60a59ab05..574bad5c5 100644 --- a/docs/plus/01-requirejs.md +++ b/docs/plus/01-requirejs.md @@ -1,5 +1,7 @@ +--- pageTitle: RequireJS menuTitle: RequireJS +--- To get Karma to run with [Require.js] we need two files: diff --git a/docs/plus/02-travis.md b/docs/plus/02-travis.md index 86d9553e6..adb8e2b1e 100644 --- a/docs/plus/02-travis.md +++ b/docs/plus/02-travis.md @@ -1,5 +1,7 @@ +--- pageTitle: Travis CI menuTitle: Travis CI +--- [Travis CI] is a popular continuous integration service that integrates with your [Github] repository to automatically run your diff --git a/docs/plus/03-jenkins.md b/docs/plus/03-jenkins.md index 4d66ebc91..056d9289c 100644 --- a/docs/plus/03-jenkins.md +++ b/docs/plus/03-jenkins.md @@ -1,5 +1,7 @@ +--- pageTitle: Jenkins CI menuTitle: Jenkins CI +--- [Jenkins CI] is one of the most popular continuous integration servers in the market today. At some point while developing your [AngularJS] diff --git a/docs/plus/04-semaphore.md b/docs/plus/04-semaphore.md index 229a3068b..ccfead39d 100644 --- a/docs/plus/04-semaphore.md +++ b/docs/plus/04-semaphore.md @@ -1,5 +1,7 @@ +--- pageTitle: Semaphore CI menuTitle: Semaphore CI +--- [Semaphore] is a popular continuous integration service that supports a [wide range of programming languages]. Up-to-date diff --git a/docs/plus/06-angularjs.md b/docs/plus/06-angularjs.md index 8c50542b6..50951da32 100644 --- a/docs/plus/06-angularjs.md +++ b/docs/plus/06-angularjs.md @@ -1,4 +1,6 @@ +--- pageTitle: AngularJS menuTitle: AngularJS +--- If you're using [AngularJS](https://angularjs.org), check out the [AngularJS Generator](https://github.com/yeoman/generator-angular), which makes use of the [Karma Generator](https://github.com/yeoman/generator-karma) to setup a fully featured, testing-ready project. diff --git a/docs/plus/08-emberjs.md b/docs/plus/08-emberjs.md index a25624089..04251ac82 100644 --- a/docs/plus/08-emberjs.md +++ b/docs/plus/08-emberjs.md @@ -1,5 +1,7 @@ +--- pageTitle: Ember.js menuTitle: Ember.js +--- To execute javascript unit and integration tests with ember.js follow the steps below: @@ -7,91 +9,91 @@ To execute javascript unit and integration tests with ember.js follow the steps 2. install the qunit plugin - ```bash - npm install karma-qunit --save-dev - ``` + ```bash + npm install karma-qunit --save-dev + ``` 3. install the ember preprocessor plugin - ```bash - npm install karma-ember-preprocessor --save-dev - ``` + ```bash + npm install karma-ember-preprocessor --save-dev + ``` 4. generate a configuration file for karma - ```bash - karma init - ``` - note -the above will walk you through the basic setup. An example configuration file that works with ember.js/qunit and phantomjs is below - - ```javascript - module.exports = function(config) { - config.set({ - basePath: 'js', - - files: [ - 'vendor/jquery/jquery.min.js', - 'vendor/handlebars/handlebars.js', - 'vendor/ember/ember.js', - 'app.js', - 'tests/*.js', - 'templates/*.handlebars' - ], - - browsers: ['PhantomJS'], - singleRun: true, - autoWatch: false, - - frameworks: ['qunit'], - - plugins: [ - 'karma-qunit', - 'karma-ember-preprocessor', - 'karma-phantomjs-launcher' - ], - - preprocessors: { - '**/*.handlebars': 'ember' - } - }); - }; - ``` - - Note - the `files` section above should include all dependencies, ie- jQuery/handlebars/ember.js along with the js and handlebars files required to deploy and run your production ember.js application - - Note - when testing ember applications, it is important that karma does not try to run the tests until the ember application has finished initialization. You will need to include a small bootstrap file in the `files` section above to enforce this. Here's an example: - ```javascript - __karma__.loaded = function() {}; - - App.setupForTesting(); - App.injectTestHelpers(); - - //this gate/check is required given that standard practice in Ember tests to is to call - //Ember.reset() in the afterEach/tearDown for each test. Doing so, causes the application - //to 're-initialize', resulting in repeated calls to the initialize function below - var karma_started = false; - App.initializer({ - name: "run tests", - initialize: function(container, application) { - if (!karma_started) { - karma_started = true; - __karma__.start(); - } - } - }); - ``` + ```bash + karma init + ``` + note -the above will walk you through the basic setup. An example configuration file that works with ember.js/qunit and phantomjs is below + + ```javascript + module.exports = function(config) { + config.set({ + basePath: 'js', + + files: [ + 'vendor/jquery/jquery.min.js', + 'vendor/handlebars/handlebars.js', + 'vendor/ember/ember.js', + 'app.js', + 'tests/*.js', + 'templates/*.handlebars' + ], + + browsers: ['PhantomJS'], + singleRun: true, + autoWatch: false, + + frameworks: ['qunit'], + + plugins: [ + 'karma-qunit', + 'karma-ember-preprocessor', + 'karma-phantomjs-launcher' + ], + + preprocessors: { + '**/*.handlebars': 'ember' + } + }); + }; + ``` + + Note - the `files` section above should include all dependencies, ie- jQuery/handlebars/ember.js along with the js and handlebars files required to deploy and run your production ember.js application + + Note - when testing ember applications, it is important that karma does not try to run the tests until the ember application has finished initialization. You will need to include a small bootstrap file in the `files` section above to enforce this. Here's an example: + ```javascript + __karma__.loaded = function() {}; + + App.setupForTesting(); + App.injectTestHelpers(); + + //this gate/check is required given that standard practice in Ember tests to is to call + //Ember.reset() in the afterEach/tearDown for each test. Doing so, causes the application + //to 're-initialize', resulting in repeated calls to the initialize function below + var karma_started = false; + App.initializer({ + name: "run tests", + initialize: function(container, application) { + if (!karma_started) { + karma_started = true; + __karma__.start(); + } + } + }); + ``` 5. add a simple Qunit test - ```javascript - test('one should equal one', function() { - equal(1, 1, 'error: one did not equal one'); - }); - ``` + ```javascript + test('one should equal one', function() { + equal(1, 1, 'error: one did not equal one'); + }); + ``` 6. run the tests with karma from the command line - ```bash - karma start - ``` + ```bash + karma start + ``` A simple unit / integration tested example app showing karma / qunit / ember in action can be found [here] diff --git a/docs/plus/09-codio.md b/docs/plus/09-codio.md index 6fc08839d..e1f84c5be 100644 --- a/docs/plus/09-codio.md +++ b/docs/plus/09-codio.md @@ -1,6 +1,6 @@ [Codio] is a web-based cloud integrated development environment that supports almost any programming language. Every project gets its individual Box: an instantly available server-side development environment with full terminal access. Unlimited panels and tabs, and a plethora of productivity features. -##Customize your Codio Project +## Customize your Codio Project Next to the help menu you will see the "Configure" option, if you don't see it click the little arrow near the end and then select "Configure". diff --git a/docs/plus/10-teamcity.md b/docs/plus/10-teamcity.md index 2ec21ab31..8d503af77 100644 --- a/docs/plus/10-teamcity.md +++ b/docs/plus/10-teamcity.md @@ -1,5 +1,7 @@ +--- pageTitle: TeamCity menuTitle: TeamCity +--- Running Karma in your [TeamCity] build is as simple as adding command line build step to perform the task. That is basically it.