From 052d7a0b5fdd38a1097939a16989b1ee9c5787e8 Mon Sep 17 00:00:00 2001
From: Connor James Smith <cjs.connor.smith@gmail.com>
Date: Fri, 26 Jan 2024 18:48:56 -0500
Subject: [PATCH] Adds `.only` and `.ignore` documentation.

Understandably the IntelliJ section was removed. This portion of the
documentation is still very useful, especially for people who are used
to being able to hit the play button on individual tests.
The old intellij sections has been moved to "Frequently Asked Questions".
---
 docs/faqs.md          | 54 +++++++++++++++++++++++++++++++++++++++++++
 website/sidebars.json |  3 +++
 2 files changed, 57 insertions(+)
 create mode 100644 docs/faqs.md

diff --git a/docs/faqs.md b/docs/faqs.md
new file mode 100644
index 00000000..842a731f
--- /dev/null
+++ b/docs/faqs.md
@@ -0,0 +1,54 @@
+---
+id: faqs 
+title: Frequently Asked Questions
+---
+
+## How do I get weaver working with IntelliJ / vscode / neovim ?
+
+Weaver provides a JUnit runner that IDEs pick up automatically. On IntelliJ the suite should have the normal button to run the tests, and Metals should provide a code lens.
+
+## How do I ignore individual tests ?
+
+An `.ignore` extension method is provided on strings, and can be used when declaring tests. All tests that are tagged with `.ignore` will be ignored in the test suite, including any that are tagged with `.only`.
+
+```scala mdoc  
+import weaver._
+import cats.effect._
+
+object MyIgnoreSuite extends SimpleIOSuite {
+
+  test("test this") {
+    IO(success)
+  }
+
+  test("do not test this".ignore) {
+    IO.raiseError(new Throwable("Boom"))
+  }
+
+}
+```
+
+## How do I run just one test in a suite? 
+
+A `.only` extension method is provided on strings, and can be used when declaring tests. When at least one test is "tagged" as such in a suite, weaver will ignore all tests but the ones that have the "only" tag. Note: `.ignore` has precedence over `.only`.
+
+```scala mdoc
+import weaver._
+import cats.effect._
+
+object MyOnlySuite extends SimpleIOSuite {
+
+  test("test this".only) {
+    IO(success)
+  }
+
+  test("do not test this") {
+    IO.raiseError(new Throwable("Boom"))
+  }
+
+}
+```
+
+### Regarding inaccurate test duration when using IntelliJ
+
+Because of modeling incompatibilities between weaver and IntelliJ, the JUnit runner is implemented in a way that makes it impossible for individual test duration to be reported correctly by the IntelliJ's test runner. Sorry about that!
diff --git a/website/sidebars.json b/website/sidebars.json
index 2b268a9b..6a071e25 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -24,6 +24,9 @@
       "multiple_suites_success",
       "multiple_suites_failures",
       "multiple_suites_logging"
+    ],
+    "Frequently Asked Questions": [
+      "faqs"
     ]
   }
 }