From 68ddbd9e75208753f39a708b952c32cd9d627086 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20Sch=C3=BC=C3=9Fler?= <git@mschuessler.org>
Date: Tue, 1 Jul 2014 02:51:47 +0200
Subject: [PATCH 1/2] :memo: Add examples for async/promise specs

---
 docs/writing-specs.md | 70 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/docs/writing-specs.md b/docs/writing-specs.md
index 118d975a3..214b0e2ed 100644
--- a/docs/writing-specs.md
+++ b/docs/writing-specs.md
@@ -38,7 +38,7 @@ Atom uses [Jasmine](http://jasmine.github.io/2.0/introduction.html) as its spec
 
 0. Add one or more expectations
 
-  The best way to learn about expectations is to read the [jasmine documentation](http://jasmine.github.io/2.0/introduction.html#section-Expectations) about them. Below is a simple example.
+  The best way to learn about expectations is to read the [jasmine documentation](http://jasmine.github.io/1.3/introduction.html#section-Expectations) about them. Below is a simple example.
 
   ```coffee
   describe "when a test is written", ->
@@ -47,6 +47,74 @@ Atom uses [Jasmine](http://jasmine.github.io/2.0/introduction.html) as its spec
       expect("oranges").not.toEqual("apples")
   ```
 
+## Asynchronous specs
+
+Writing Asynchronous specs can be tricky at first. Some examples.
+
+0. Promises
+
+  Working with promises is rather easy in Atom. You can use our `waitsForPromise` function.
+
+  ```coffee
+    describe "when we open a file", ->
+      it "should be opened in an editor", ->
+        waitsForPromise ->
+          atom.workspace.open 'c.coffee'
+          .then (editor) -> expect(editor.getPath()).toContain 'c.coffee'
+  ```
+
+  This method can be used in the `describe`, `it`, `beforeEach` and `afterEach` functions.
+
+  ```coffee
+  describe "when we open a file", ->
+    beforeEach ->
+      waitsForPromise ->
+        atom.workspace.open 'c.coffee'
+
+    it "should be opened in an editor", ->
+      expect(atom.workspace.getActiveEditor().getPath()).toContain 'c.coffee'
+
+  ```
+
+  If you need to wait for multiple promises use a new `waitsForPromise` function for each promise. (Caution: Without `beforeEach` this example will fail!)
+
+  ```coffee
+  describe "waiting for the packages to load", ->
+
+    beforeEach ->
+      waitsForPromise ->
+        atom.workspace.open('sample.js')
+      waitsForPromise ->
+        atom.packages.activatePackage('tabs')
+      waitsForPromise ->
+        atom.packages.activatePackage('tree-view')
+
+    it 'should have waited long enough', ->
+      expect(atom.packages.isPackageActive('tabs')).toBe true
+      expect(atom.packages.isPackageActive('tree-view')).toBe true
+  ```
+
+0. Asynchronous functions with callbacks
+
+  Specs for asynchronous functions can be done using the `waitsFor` and `runs` functions. A simple example.
+
+  ```coffee
+  describe "fs.readdir(path, cb)", ->
+    it "is async", ->
+      spy = jasmine.createSpy('fs.readdirSpy')
+
+      fs.readdir('/tmp/example', spy)
+      waitsFor ->
+        spy.callCount > 0
+      runs ->
+        exp = [null, ['example.coffee']]
+        expect(spy.mostRecentCall.args).toEqual exp
+        expect(spy).toHaveBeenCalledWith(null, ['example.coffee'])
+  ```
+
+For a more detailed documentation on asynchronous tests please visit the [jasmine documentation](http://jasmine.github.io/1.3/introduction.html#section-Asynchronous_Support).
+
+
 ## Running specs
 
 Most of the time you'll want to run specs by triggering the `window:run-package-specs` command. This command is not only to run package specs, it is also for Atom core specs. This will run all the specs in the current project's spec directory. If you want to run the Atom core specs and **all** the default package specs trigger the `window:run-all-specs` command.

From 5753680b585d8d981ed1deefdab5fb4590de8326 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20Sch=C3=BC=C3=9Fler?= <git@mschuessler.org>
Date: Tue, 1 Jul 2014 13:26:47 +0200
Subject: [PATCH 2/2] Minor changes

---
 docs/writing-specs.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/writing-specs.md b/docs/writing-specs.md
index 214b0e2ed..d6456daf1 100644
--- a/docs/writing-specs.md
+++ b/docs/writing-specs.md
@@ -59,11 +59,11 @@ Writing Asynchronous specs can be tricky at first. Some examples.
     describe "when we open a file", ->
       it "should be opened in an editor", ->
         waitsForPromise ->
-          atom.workspace.open 'c.coffee'
-          .then (editor) -> expect(editor.getPath()).toContain 'c.coffee'
+          atom.workspace.open('c.coffee').then (editor) ->
+            expect(editor.getPath()).toContain 'c.coffee'
   ```
 
-  This method can be used in the `describe`, `it`, `beforeEach` and `afterEach` functions.
+  This method can be used in the `describe`, `it`, `beforeEach`, `afterEach` and `runs`  functions.
 
   ```coffee
   describe "when we open a file", ->