From ac810d54f38f8c6a1408c21ddef48da848c91b92 Mon Sep 17 00:00:00 2001
From: Katrin Shechtman <katrin.shechtman@gmail.com>
Date: Thu, 18 Feb 2016 02:22:13 -0500
Subject: [PATCH] adding testing section to scalajs website including how to
 have integration testing aka it:test

---
 .htaccess              |  6 ++++
 _data/doc.yml          |  2 ++
 doc/project/testing.md | 65 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+)
 create mode 100644 doc/project/testing.md

diff --git a/.htaccess b/.htaccess
index e07cddbe..ceb55ab1 100644
--- a/.htaccess
+++ b/.htaccess
@@ -1,5 +1,11 @@
 ---
 ---
+
+{% comment %}
+Update this file if you have an entry that you are moving around.
+Don't update this file if you are adding a new entry.
+{% endcomment %}
+
 redirect 301 /doc/tutorial.html {{ BASE_PATH }}/tutorial/basic/
 
 redirect 301 /doc/calling-javascript.html {{ BASE_PATH }}/doc/interoperability/facade-types.html
diff --git a/_data/doc.yml b/_data/doc.yml
index 85015041..d03649a3 100644
--- a/_data/doc.yml
+++ b/_data/doc.yml
@@ -22,6 +22,8 @@
       url: /doc/project/js-environments.html
     - text: Cross-building
       url: /doc/project/cross-build.html
+    - text: Testing
+      url: /doc/project/testing.html  
 - text: JavaScript interoperability
   url: /doc/interoperability/
   subitems:
diff --git a/doc/project/testing.md b/doc/project/testing.md
new file mode 100644
index 00000000..49823889
--- /dev/null
+++ b/doc/project/testing.md
@@ -0,0 +1,65 @@
+---
+layout: doc
+title: Testing
+---
+
+In this section we will discuss how to test Scala.js code managed as [Full cross project](./cross-build.html). All names
+for example subproject name such as `fooJVM` are taken from 
+[cross compile example](https://github.com/scala-js/scalajs-cross-compile-example).
+
+## Directory Structure
+
+    <project root>
+     +- jvm
+     |   +- src/main/scala
+     |   +- src/test/scala
+     +- js
+     |   +- src/main/scala
+     |   +- src/test/scala
+     +- shared
+         +- src/main/scala
+         +- src/test/scala
+
+Similarly to `{shared|js|jvm}/src/main/scala` folders that contain your code, there can be also
+`{shared|js|jvm}/src/test/scala` folders that would contain your tests. Tests that verify correctness of shared code
+should go to `shared` test folder, while tests that check Scala JVM code or Scala.js code only should go to `jvm` or
+`js` test folders respectively. Calling `sbt> fooJVM/test` will execute all tests residing in `shared` and `jvm`
+folders, thus testing Scala JVM code. Calling `sbt> fooJS/test` will execute all tests residing in `shared` and `js`
+folders, so Scala.js code is tested. In case of the full cross project, root project aggregates JVM and JS
+parts, so when calling `sbt> test` will effectively run both `fooJVM/test` and `fooJS/test`.
+
+## Integration testing
+
+Configuring a regular non-Scala.js sbt project to have `it:test` is a well described task, see 
+[documentation](http://www.scala-sbt.org/0.13/docs/Testing.html#Integration+Tests) for more details.
+In a `CrossProject` it won't work out-of-the-box because of 2 reasons. First reason is that by default Scala JVM and
+Scala.js `it` configurations won't be aware of `shared/src/it/scala` folder. Second is that Scala.js `it` configuration
+by default does not contain `ScalaJSClassLoader` definition required for running Scala.js tests. To fix that you need to
+add the following settings to the crossProject definition along with `IntegrationTest` settings:
+
+{% highlight scala %}
+lazy val cross = crossProject.in(file(".")).
+  ...
+  // adding the `it` configuration
+  configs(IntegrationTest).
+  // adding `it` tasks
+  settings(Defaults.itSettings:_*).
+  // add `shared` folder to `jvm` source directories
+  jvmSettings(unmanagedSourceDirectories in IntegrationTest ++=
+    CrossType.Full.sharedSrcDir(baseDirectory.value, "it").toSeq).
+  // add `shared` folder to `js` source directories
+  jsSettings(unmanagedSourceDirectories in IntegrationTest ++=
+    CrossType.Full.sharedSrcDir(baseDirectory.value, "it").toSeq).
+  // adding ScalaJSClassLoader to `js` configuration
+  jsSettings(inConfig(IntegrationTest)(ScalaJSPluginInternal.scalaJSTestSettings):_*) 
+{% endhighlight %}
+
+Now you can put tests in `{shared|jvm|js}/src/it/scala` and they will run when you call `sbt> it:test`. Similarly to
+`test`, there is also two iterations and they can be executed separately by explicitely stating jvm or js project name,
+for example `sbt> fooJS/it:test`.
+
+## Testing frameworks
+
+A list of testing frameworks compatible with Scala.js can be found [here](../../libraries/testing.html).
+
+Note: Don't forget to mark a test framework SBT dependency as `test,it` if you have both unit and integration tests.