From 20b0f081669e390b5757b766fac27645f6ec3891 Mon Sep 17 00:00:00 2001
From: Chris Rudolphi <1702962+clrudolphi@users.noreply.github.com>
Date: Sun, 9 Nov 2025 10:05:18 -0600
Subject: [PATCH] Draft update to the documentation on the topic of tag
 expressions

---
 docs/automation/scoped-bindings.md | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/docs/automation/scoped-bindings.md b/docs/automation/scoped-bindings.md
index 8401c1025..613c4b8ec 100644
--- a/docs/automation/scoped-bindings.md
+++ b/docs/automation/scoped-bindings.md
@@ -6,7 +6,7 @@ In some cases however, it is necessary to restrict when step definitions or hook
 
 You can restrict the execution of scoped bindings by:
 
-- tag
+- tag expression
 - feature (using the feature title)
 - scenario (using the scenario title)
 
@@ -28,6 +28,23 @@ Use the `[Scope]` attribute to define the scope:
 [Scope(Tag = "mytag", Feature = "feature title", Scenario = "scenario title")]
 ```
 
+## Tag expressions
+A tag expression is an infix boolean expression. Below are some examples:
+
+|Expression|Description|
+|----------|-----------|
+|@fast|	Scenarios tagged with @fast|
+|@wip and not @slow|	Scenarios tagged with @wip that aren't also tagged with @slow|
+|@smoke and @fast|	Scenarios tagged with both @smoke and @fast|
+|@gui or @database|	Scenarios tagged with either @gui or @database|
+
+```{note}
+The '@' prefix is optional within a tag expression.
+```
+For even more advanced tag expressions you can use parenthesis for clarity, or to change operator precedence:
+
+    (@smoke or @ui) and (not @slow)
+
 ## Scoping Rules
 
 Scope can be defined at the method or class level.
@@ -47,8 +64,7 @@ The following example combines the tag scopes with "OR":
 
 ```{code-block} csharp
 :caption: Step Definition File
-[Scope(Tag = "thisTag")] [Scope(Tag = "OrThisTag")]
-[Scope(Tag = "thisTag"), Scope(Tag = "OrThisTag")]
+[Scope(Tag = "thisTag or thatTag", Feature = "thisFeature")] [Scope(Tag = "OrThisTag", Feature="thatFeature")]
 ```
 
 ````{note}
@@ -103,6 +119,7 @@ public void PerformSimpleSearch(string title)
 }
 ```
 
+
 ## Scoping Tips & Tricks
 
 The following example shows a way to "ignore" executing the scenarios marked with `@manual`. However Reqnroll's tracing will still display the steps, so you can work through the manual scenarios by following the steps in the report.
@@ -129,6 +146,11 @@ public class ManualSteps
 }
 ```
 
+```{note}
+Can this next section be deleted completely, given that tag expressions can now perform what the example attempts to show?
+If we wish to retain this section, we need a more compelling example.
+```
+
 ## Beyond Scope
 
 You can define more complex filters using the [`ScenarioContext`](scenario-context.md) class. The following example starts selenium if the scenario is tagged with `@web` _and_ `@automated`.