User Guide updates.

This commit is contained in:
Christian Williams 2010-08-05 00:48:03 -07:00
parent 7820629e18
commit 08c42d22a3

View File

@ -51,29 +51,29 @@ The result is Jasmine, and we love test-driving our code with it. Enjoy.
How To How To
------ ------
There is a simple example of how to use Jasmine in the /example directory. But here's more information. There is a simple example of how to use Jasmine in the /example directory, but here's more information.
### Specs ### Specs
Each spec is, naturally, a JavaScript function. You tell Jasmine about this spec with a call to `it()` with a string and the function. The string is a description that will be helpful to you when reading a report. Each spec is, naturally, a JavaScript function. You tell Jasmine about a spec with a call to `it()` with a description string and the function. The string is a description of a behavior that you want your production code to exhibit; it should be meaningful to you when reading a report.
it('should be a test', function () { it('should increment a variable', function () {
var foo = 0; var foo = 0;
foo++; foo++;
}); });
### Expectations ### Expectations
Within your spec you will want to express expectations about the behavior of your application code. These are made with the `expect()` function and expectation matchers, like this: Within your spec you will express expectations about the behavior of your application code. This is done using the `expect()` function and any of various expectation matchers, like this:
it('should be a test', function () { it('should increment a variable', function () {
var foo = 0; // set up the world var foo = 0; // set up the world
foo++; // call your application code foo++; // call your application code
expect(foo).toEqual(1); // passes because foo == 1 expect(foo).toEqual(1); // passes because foo == 1
}); });
Results of the expectations are logged for later for reporting. Results of the expectations will be reported to you when the spec is run.
#### Expectation Matchers #### Expectation Matchers
@ -81,6 +81,8 @@ Jasmine has several built-in matchers. Here are a few:
>`expect(x).toEqual(y);` compares objects or primitives `x` and `y` and passes if they are equivalent >`expect(x).toEqual(y);` compares objects or primitives `x` and `y` and passes if they are equivalent
> >
>`expect(x).toBe(y);` compares objects or primitives `x` and `y` and passes if they are the same object
>
>`expect(x).toMatch(pattern);` compares `x` to string or regular expression `pattern` and passes if they match >`expect(x).toMatch(pattern);` compares `x` to string or regular expression `pattern` and passes if they match
> >
>`expect(x).toBeDefined();` passes if `x` is not `undefined` >`expect(x).toBeDefined();` passes if `x` is not `undefined`
@ -92,6 +94,12 @@ Jasmine has several built-in matchers. Here are a few:
>`expect(x).toBeFalsy();` passes if `x` evaluates to false >`expect(x).toBeFalsy();` passes if `x` evaluates to false
> >
>`expect(x).toContain(y);` passes if array or string `x` contains `y` >`expect(x).toContain(y);` passes if array or string `x` contains `y`
>
>`expect(x).toBeLessThan(y);` passes if `x` is less than `y`
>
>`expect(x).toBeGreaterThan(y);` passes if `x` is greater than `y`
>
>`expect(fn).toThrow(e);` passes if function `fn` throws exception `e` when executed
Every matcher's criteria can be inverted by prepending `.not`: Every matcher's criteria can be inverted by prepending `.not`:
@ -121,37 +129,39 @@ To add the matcher to your suite, call `this.addMatchers()` from within a `befor
Specs are grouped in Suites. Suites are defined using the global `describe()` function: Specs are grouped in Suites. Suites are defined using the global `describe()` function:
describe('One suite', function () { describe('Calculator', function () {
it('has a test', function () { it('can add a number', function () {
... ...
}); });
it('has another test', function () { it('has multiply some numbers', function () {
... ...
}); });
}); });
The Suite name is so that reporting is more descriptive. The Suite name is typically the name of a class or other applicaton component, and will be reported with results when your specs are run.
Suites are executed in the order in which `describe()` calls are made, usually in the order in which their script files are included. Additionally, specs within a suite share a functional scope. So you may declare variables inside a describe block and they are accessible from within your specs. For example: Suites are executed in the order in which `describe()` calls are made, usually in the order in which their script files are included. Additionally, specs within a suite share a functional scope. So you may declare variables inside a describe block and they are accessible from within your specs. For example:
describe('A suite with some variables', function () { describe('Calculator', function () {
var bar = 0 var counter = 0
it('has a test', function () { it('can add a number', function () {
bar++; counter = counter + 2; // counter was 0 before
expect(bar).toEqual(1); expect(bar).toEqual(2);
}); });
it('has another test', function () { it('can multiply a number', function () {
bar++; counter = counter * 5; // counter was 2 before
expect(bar).toEqual(2); expect(bar).toEqual(10);
}); });
}); });
Be aware that code directly inside the `describe()` function is only executed once, which is why `counter` in the above example is not reset to `0` for the second spec. If you want to initialize variables before each spec, use a `beforeEach()` function.
#### beforeEach #### beforeEach
A suite can have a beforeEach declaration. It takes a function that is run before each spec. For example: A suite can have a `beforeEach()` declaration. It takes a function that is run before each spec. For example:
describe('some suite', function () { describe('some suite', function () {
@ -166,7 +176,7 @@ A suite can have a beforeEach declaration. It takes a function that is run befor
}); });
}); });
A runner can also have beforeEach declarations. Runner beforeEach functions are executed before every spec in all suites, and execute BEFORE suite beforeEach functions. For example: A runner can also have `beforeEach()` declarations. Runner `beforeEach()` functions are executed before every spec in all suites, and execute BEFORE suite `beforeEach()` functions. For example:
var runnerWideFoo = []; var runnerWideFoo = [];
@ -187,7 +197,7 @@ A runner can also have beforeEach declarations. Runner beforeEach functions are
#### afterEach #### afterEach
Similarly, there is an afterEach declaration. It takes a function that is run after each spec. For example: Similarly, there is an `afterEach()` declaration. It takes a function that is run after each spec. For example:
describe('some suite', function () { describe('some suite', function () {
@ -205,7 +215,7 @@ Similarly, there is an afterEach declaration. It takes a function that is run a
}; };
}); });
A runner can also have an afterEach declarations. Runner afterEach functions are executed after every spec in all suites, and execute AFTER suite afterEach functions. For example: A runner can also have an `afterEach()` declarations. Runner `afterEach()` functions are executed after every spec in all suites, and execute AFTER suite `afterEach()` functions. For example:
var runnerWideFoo = []; var runnerWideFoo = [];
@ -242,6 +252,7 @@ A spec may ask Jasmine to execute some code after the spec has finished running;
### Nested Describes ### Nested Describes
Jasmine supports nested describes. An example: Jasmine supports nested describes. An example:
describe('some suite', function () { describe('some suite', function () {
@ -363,7 +374,7 @@ Spies are automatically removed after each spec. They may be set in the beforeEa
### Disabling Tests & Suites ### Disabling Tests & Suites
Specs may be disabled by calling `xit()` instead of `it()`. Suites may be disabled by calling `xdescribe()` instead of `describe()`. A simple find/replace in your editor of choice will allow you to run a subset of your specs. Specs may be disabled by calling `xit()` instead of `it()`. Suites may be disabled by calling `xdescribe()` instead of `describe()`.
### Asynchronous Specs ### Asynchronous Specs
@ -481,5 +492,5 @@ We welcome your contributions! Jasmine is currently maintained by Davis Frank ([
## Acknowledgments ## Acknowledgments
* A big shout out to the various JavaScript test framework authors, especially TJ for [JSpec](http://github.com/visionmedia/jspec/tree/master) - we played with it a bit before deciding that we really needed to roll our own. * A big shout out to the various JavaScript test framework authors, especially TJ for [JSpec](http://github.com/visionmedia/jspec/tree/master) - we played with it a bit before deciding that we really needed to roll our own.
* Thanks to Pivot [Jessica Miller](http://www.jessicamillerworks.com/) for our fancy pass/fail/pending icons * Thanks to Pivot [Jessica Miller](http://www.jessicamillerworks.com/) for our logo and fancy pass/fail/pending icons
* Huge contributions have been made by [Adam Abrons](mailto:adam@pivotallabs.com), [Lee Byrd](mailto:lee@pivotallabs.com), [Erik Hanson](mailto:erik@pivotallabs.com), [Carl Jackson](mailto:carl@pivotallabs.com), and many other Pivots. * Huge contributions have been made by [Adam Abrons](mailto:adam@pivotallabs.com), [Lee Byrd](mailto:lee@pivotallabs.com), [Erik Hanson](mailto:erik@pivotallabs.com), [Carl Jackson](mailto:carl@pivotallabs.com), and many other Pivots.