Skip to content

Commit

Permalink
docs: updates to the documentation to support new markdown renderer (#…
Browse files Browse the repository at this point in the history
…3672)


Companion PR for karma-runner/karma-runner.github.com#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
  • Loading branch information
devoto13 authored Apr 12, 2021
1 parent cc9420d commit 94cf15e
Show file tree
Hide file tree
Showing 18 changed files with 122 additions and 95 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
3 changes: 2 additions & 1 deletion docs/about/03-migration.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/dev/01-contributing.md
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
4 changes: 2 additions & 2 deletions docs/dev/03-maintaining.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
30 changes: 15 additions & 15 deletions docs/dev/04-public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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`.

Expand Down Expand Up @@ -310,25 +310,25 @@ 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
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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/dev/05-plugins.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
2 changes: 2 additions & 0 deletions docs/dev/06-git-commit-msg.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
---
showInMenu: false
---

## The reasons for these conventions:
- automatic generating of the changelog
Expand Down
2 changes: 2 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
---
layout: homepage
pageTitle: Spectacular Test Runner for Javascript
---
2 changes: 2 additions & 0 deletions docs/intro/04-faq.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 2 additions & 0 deletions docs/intro/05-troubleshooting.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
2 changes: 2 additions & 0 deletions docs/plus/01-requirejs.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
pageTitle: RequireJS
menuTitle: RequireJS
---

To get Karma to run with [Require.js] we need two files:

Expand Down
2 changes: 2 additions & 0 deletions docs/plus/02-travis.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/plus/03-jenkins.md
Original file line number Diff line number Diff line change
@@ -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]
Expand Down
2 changes: 2 additions & 0 deletions docs/plus/04-semaphore.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/plus/06-angularjs.md
Original file line number Diff line number Diff line change
@@ -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.
152 changes: 77 additions & 75 deletions docs/plus/08-emberjs.md
Original file line number Diff line number Diff line change
@@ -1,97 +1,99 @@
---
pageTitle: Ember.js
menuTitle: Ember.js
---

To execute javascript unit and integration tests with ember.js follow the steps below:

1. [install karma]

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]
Expand Down
2 changes: 1 addition & 1 deletion docs/plus/09-codio.md
Original file line number Diff line number Diff line change
@@ -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".

Expand Down
2 changes: 2 additions & 0 deletions docs/plus/10-teamcity.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down

0 comments on commit 94cf15e

Please sign in to comment.