From 4c95c2db29f678f828c5affe4b490167db329bf9 Mon Sep 17 00:00:00 2001
From: zainab-ali <zainab@kebab-ca.se>
Date: Mon, 12 Jan 2026 12:04:58 +0000
Subject: [PATCH] Improve guide on filtering tests.

---
 docs/features/directory.conf |  1 -
 docs/features/filtering.md   | 73 +++++++++++++++++++++++++++++++++++-
 docs/features/tagging.md     | 26 -------------
 3 files changed, 72 insertions(+), 28 deletions(-)
 delete mode 100644 docs/features/tagging.md

diff --git a/docs/features/directory.conf b/docs/features/directory.conf
index cbc2d050..dbc41dc1 100644
--- a/docs/features/directory.conf
+++ b/docs/features/directory.conf
@@ -6,7 +6,6 @@ laika.navigationOrder = [
  resources.md,
  global_resources.md,
  logging.md,
- tagging.md,
  scalacheck.md,
  discipline.md,
  parallelism.md,
diff --git a/docs/features/filtering.md b/docs/features/filtering.md
index 7bc3e36e..26deca9f 100644
--- a/docs/features/filtering.md
+++ b/docs/features/filtering.md
@@ -1,7 +1,9 @@
 Filtering tests
 ===============
 
-When using the IOSuite variants, the user can call `sbt`'s test command as such:
+## Running a subset of tests
+
+You can run a set of tests with `sbt` using the `testOnly` command:
 
 ``` 
 > testOnly -- -o *foo*
@@ -12,3 +14,72 @@ This filter will prevent the execution of any test that doesn't contain the stri
 ```
 fooPackage.FooSuite.foo
 ```
+
+## Running a single test
+
+You can run a single test in a suite by appending `only` to the test name:
+
+```scala mdoc
+import weaver._
+
+object ExampleSuite extends FunSuite {
+
+  test("Only run this test".only) {
+    expect.eql(1, 2)
+  }
+  
+  test("This test will not be run") {
+      expect.eql(1, 1)
+  }
+}
+```
+
+## Ignoring tests
+
+You can mark a test as ignored by appending `ignore` to the test name. The test will not be run as part of your test suite.
+
+```scala mdoc
+import weaver._
+
+object IgnoreSuite extends FunSuite {
+
+  test("This test is not run".ignore) {
+    expect.eql(1, 2)
+  }
+  test("This test is run") {
+    expect.eql(1, 1)
+  }
+}
+```
+
+### Example report
+
+```scala mdoc:passthrough 
+println(weaver.docs.Output.runSuites(IgnoreSuite))
+```
+
+## Dynamically ignoring tests
+
+You can also dynamically mark tests as ignored using the `ignore` function:
+
+```scala mdoc
+import weaver._
+import cats.effect.IO
+import cats.syntax.all._
+
+object DynamicIgnoreSuite extends SimpleIOSuite {
+
+  test("Only on CI") {
+    for {
+      onCI <- IO(sys.env.get("CI").isDefined)
+      _    <- ignore("not on CI").unlessA(onCI)
+    } yield expect.eql(1, 2)
+  }
+}
+```
+
+### Example report
+
+```scala mdoc:passthrough 
+println(weaver.docs.Output.runSuites(DynamicIgnoreSuite))
+```
diff --git a/docs/features/tagging.md b/docs/features/tagging.md
deleted file mode 100644
index adb1fce1..00000000
--- a/docs/features/tagging.md
+++ /dev/null
@@ -1,26 +0,0 @@
-Tagging
-=======
-
-Weaver provides some constructs to dynamically tag tests as `ignored` :
-
-```scala mdoc
-import weaver._
-import cats.effect.IO
-import cats.syntax.all._
-
-object TaggingSuite extends SimpleIOSuite {
-
-  test("Only on CI") {
-    for {
-      onCI <- IO(sys.env.get("CI").isDefined)
-      _    <- ignore("not on CI").unlessA(onCI)
-      x    <- IO.delay(1)
-      y    <- IO.delay(2)
-    } yield expect(x == y)
-  }
-}
-```
-
-```scala mdoc:passthrough 
-println(weaver.docs.Output.runSuites(TaggingSuite))
-```