From 08c42d22a3de75da912b8ac280c68bb3d33f01d7 Mon Sep 17 00:00:00 2001 From: Christian Williams Date: Thu, 5 Aug 2010 00:48:03 -0700 Subject: [PATCH] User Guide updates. --- user-guide.html.markdown | 59 ++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/user-guide.html.markdown b/user-guide.html.markdown index da65235..d8e182f 100644 --- a/user-guide.html.markdown +++ b/user-guide.html.markdown @@ -51,29 +51,29 @@ The result is Jasmine, and we love test-driving our code with it. Enjoy. 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 -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; foo++; }); ### 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 foo++; // call your application code 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 @@ -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).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).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).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`: @@ -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: - describe('One suite', function () { - it('has a test', function () { + describe('Calculator', 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: - describe('A suite with some variables', function () { - var bar = 0 + describe('Calculator', function () { + var counter = 0 - it('has a test', function () { - bar++; - expect(bar).toEqual(1); + it('can add a number', function () { + counter = counter + 2; // counter was 0 before + expect(bar).toEqual(2); }); - it('has another test', function () { - bar++; - expect(bar).toEqual(2); + it('can multiply a number', function () { + counter = counter * 5; // counter was 2 before + 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 -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 () { @@ -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 = []; @@ -187,7 +197,7 @@ A runner can also have beforeEach declarations. Runner beforeEach functions are #### 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 () { @@ -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 = []; @@ -242,6 +252,7 @@ A spec may ask Jasmine to execute some code after the spec has finished running; ### Nested Describes + Jasmine supports nested describes. An example: 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 -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 @@ -481,5 +492,5 @@ We welcome your contributions! Jasmine is currently maintained by Davis Frank ([ ## 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. -* 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.