Add WAITFOR DELAY '<time>' / WAITFOR DELAY @variable backed by Thread.Sleep(TimeSpan); strict operand grammar (literal or @var only, time-typed var raises Msg 9815, cast/integer/bare NULL fail at parse), Msg 148 verbatim for bad time strings, empty string and NULL-valued variable silently no-op; WAITFOR TIME is NotSupportedException; cancellation-token gap documented.

RyanLamansky · RyanLamansky · commit fde4588b6ce3 · 2026-05-11T10:14:24.000-05:00
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -383,6 +383,9 @@ Probe-confirmed semantics (2026-05-11) the simulator handles correctly because e
 - Real SQL Server's PRINT truncates messages at 8000 chars (varchar) / 4000 chars (nvarchar). Simulator: no truncation modeled (output is discarded).
 - Real SQL Server raises **Msg 1046** ("Subqueries are not allowed in this context. Only scalar expressions are allowed.") for `PRINT (SELECT 'inner')`. The simulator silently evaluates the scalar subquery — Msg 1046 isn't modeled.
 
+### `WAITFOR DELAY`
+`WAITFOR DELAY '<time>'` and `WAITFOR DELAY @variable` block the calling thread via `Thread.Sleep(TimeSpan)`, matching real SQL Server's "blocks the connection" semantics. Operand grammar is strict (matches probe of SQL Server 2025, 2026-05-11): only a varchar/nvarchar string literal or an `@-variable` reference. `cast(...)`, integer literal, bare `NULL` literal all fail at parse (Msg 102/156); `time`-typed variable raises **Msg 9815** (`"Waitfor delay and waitfor time cannot be of type time."` — note SQL Server reserves the operand slot for *string-typed* values, not its own `time` type). Empty string and NULL-valued variable both silently succeed as zero delay. Bad-format string raises **Msg 148** with the offending value embedded. `@@ROWCOUNT` resets to 0. Skip-mode suppresses the sleep entirely (an `IF 1=0 WAITFOR DELAY '00:00:10'` returns instantly). **`WAITFOR TIME`** (absolute-time wait) raises `NotSupportedException` — scheduling-style primitive not yet needed. **Cancellation gap**: an `ExecuteReaderAsync` caller's `CancellationToken` isn't threaded into the sleep; the thread blocks until the duration elapses regardless.
+
 ### Local temp tables (`#foo`)
 Per-connection `Dictionary<string, HeapTable> TempTables` on `SimulatedDbConnection`; routed by `BatchContext.TryResolveTable` (`#`-prefix → connection dict, else current DB + system tables). Auto-cleared on `Dispose`, matching real SQL Server's session-close drop. Lifecycle, cross-conn isolation, and Msg 208 from other sessions all probe-confirmed against SQL Server 2025.
 
diff --git a/SqlServerSimulator.Tests/WaitForDelayTests.cs b/SqlServerSimulator.Tests/WaitForDelayTests.cs
@@ -0,0 +1,210 @@
+using System.Data.Common;
+using System.Diagnostics;
+using static Microsoft.VisualStudio.TestTools.UnitTesting.Assert;
+
+namespace SqlServerSimulator;
+
+/// <summary>
+/// Tests for <c>WAITFOR DELAY</c>. The simulator uses
+/// <see cref="Thread.Sleep(TimeSpan)"/> on the calling thread, matching real
+/// SQL Server's "blocks the connection" semantics. To keep CI fast, only
+/// one test actually sleeps a non-trivial duration; everything else
+/// exercises parsing / dispatch / skip-mode / error paths with a
+/// <c>'00:00:00'</c> operand. Behavior probed against SQL Server 2025
+/// (2026-05-11).
+/// </summary>
+[TestClass]
+public sealed class WaitForDelayTests
+{
+    [TestMethod]
+    public void Delay_Zero_StringLiteral_ReturnsImmediately()
+        => _ = new Simulation().ExecuteNonQuery("waitfor delay '00:00:00'");
+
+    [TestMethod]
+    public void Delay_EmptyString_ReturnsImmediately()
+    {
+        // Probe-confirmed: empty string is silently accepted as zero delay.
+        _ = new Simulation().ExecuteNonQuery("waitfor delay ''");
+    }
+
+    [TestMethod]
+    public void Delay_Variable_String_ReturnsImmediately()
+        => _ = new Simulation().ExecuteNonQuery(
+            "declare @t varchar(20) = '00:00:00'; waitfor delay @t");
+
+    [TestMethod]
+    public void Delay_Variable_NullValue_ReturnsImmediately()
+    {
+        // Probe-confirmed: a NULL-valued variable is silently accepted as
+        // zero delay (distinct from the bare NULL literal which is a Msg 156
+        // syntax error at parse time — different code path).
+        _ = new Simulation().ExecuteNonQuery(
+            "declare @t varchar(20); waitfor delay @t");
+    }
+
+    /// <summary>
+    /// The only test that actually sleeps. ~50ms is well under the user's
+    /// 100ms ceiling; the assertion checks the sleep was at least nearly
+    /// the requested span (giving 10ms of OS scheduler slack on the lower
+    /// bound) and not absurdly long.
+    /// </summary>
+    [TestMethod]
+    public void Delay_50ms_ActuallySleeps()
+    {
+        var start = Stopwatch.GetTimestamp();
+        _ = new Simulation().ExecuteNonQuery("waitfor delay '00:00:00.050'");
+        var elapsed = Stopwatch.GetElapsedTime(start);
+        IsGreaterThanOrEqualTo(40, elapsed.TotalMilliseconds,
+            $"Expected ≥40ms sleep, got {elapsed.TotalMilliseconds}ms");
+        IsLessThan(500, elapsed.TotalMilliseconds,
+            $"Expected <500ms sleep, got {elapsed.TotalMilliseconds}ms");
+    }
+
+    [TestMethod]
+    public void Delay_InUntakenIf_DoesNotSleep()
+    {
+        // The string operand here would otherwise sleep 10 seconds — verify
+        // skip-mode suppresses the actual sleep.
+        var start = Stopwatch.GetTimestamp();
+        _ = new Simulation().ExecuteNonQuery("if 1=0 waitfor delay '00:00:10'");
+        var elapsed = Stopwatch.GetElapsedTime(start);
+        IsLessThan(100, elapsed.TotalMilliseconds,
+            $"Expected near-instant skip, got {elapsed.TotalMilliseconds}ms");
+    }
+
+    [TestMethod]
+    public void Delay_AfterReturn_DoesNotSleep()
+    {
+        var start = Stopwatch.GetTimestamp();
+        _ = new Simulation().ExecuteNonQuery("return; waitfor delay '00:00:10'");
+        var elapsed = Stopwatch.GetElapsedTime(start);
+        IsLessThan(100, elapsed.TotalMilliseconds,
+            $"Expected near-instant skip, got {elapsed.TotalMilliseconds}ms");
+    }
+
+    [TestMethod]
+    public void Delay_AfterBreak_DoesNotSleep()
+    {
+        var start = Stopwatch.GetTimestamp();
+        _ = new Simulation().ExecuteNonQuery("""
+            while 1=1
+            begin
+                break;
+                waitfor delay '00:00:10';
+            end
+            """);
+        var elapsed = Stopwatch.GetElapsedTime(start);
+        IsLessThan(100, elapsed.TotalMilliseconds,
+            $"Expected near-instant skip, got {elapsed.TotalMilliseconds}ms");
+    }
+
+    [TestMethod]
+    public void Delay_ResetsRowCountToZero()
+    {
+        using var reader = new Simulation().ExecuteReader("""
+            select 1 union all select 2 union all select 3;
+            waitfor delay '00:00:00';
+            select @@rowcount as rc
+            """);
+        while (reader.Read()) { }
+        IsTrue(reader.NextResult());
+        IsTrue(reader.Read());
+        AreEqual(0, reader.GetInt32(0));
+    }
+
+    [TestMethod]
+    public void Delay_MalformedString_Msg148()
+        => new Simulation().AssertSqlError(
+            "waitfor delay 'not a time'", 148,
+            "Incorrect time syntax in time string 'not a time' used with WAITFOR.");
+
+    [TestMethod]
+    public void Delay_Over24h_Msg148()
+        => new Simulation().AssertSqlError("waitfor delay '25:00:00'", 148);
+
+    [TestMethod]
+    public void Delay_NegativeString_Msg148()
+        => new Simulation().AssertSqlError("waitfor delay '-00:00:01'", 148);
+
+    [TestMethod]
+    public void Delay_DayComponent_Msg148()
+        => new Simulation().AssertSqlError("waitfor delay '99:00:00:00'", 148);
+
+    [TestMethod]
+    public void Delay_BadVariableValue_Msg148()
+        => new Simulation().AssertSqlError(
+            "declare @t varchar(20) = 'bogus'; waitfor delay @t", 148,
+            "Incorrect time syntax in time string 'bogus' used with WAITFOR.");
+
+    [TestMethod]
+    public void Delay_TimeTypedVariable_Msg9815()
+        => new Simulation().AssertSqlError(
+            "declare @t time = '00:00:00.100'; waitfor delay @t", 9815,
+            "Waitfor delay and waitfor time cannot be of type time.");
+
+    [TestMethod]
+    public void Delay_IntegerLiteralOperand_SyntaxError()
+    {
+        // Real SQL Server raises Msg 102 here; the simulator routes through
+        // the same Msg-102 factory (SyntaxErrorNear).
+        var ex = Throws<DbException>(
+            () => _ = new Simulation().ExecuteNonQuery("waitfor delay 1"));
+        AreEqual("102", ex.Data["HelpLink.EvtID"]);
+    }
+
+    [TestMethod]
+    public void Delay_BareNullLiteralOperand_SyntaxError()
+    {
+        // Real SQL Server: Msg 156 "Incorrect syntax near the keyword 'null'."
+        // Simulator: Msg 102 (NULL falls through to the operand's
+        // SyntaxErrorNear catch-all). Wording differs but rejection is
+        // consistent — a hand-typed `waitfor delay null` is a programmer
+        // error either way.
+        var ex = Throws<DbException>(
+            () => _ = new Simulation().ExecuteNonQuery("waitfor delay null"));
+        var num = ex.Data["HelpLink.EvtID"] as string;
+        IsTrue(num is "102" or "156", $"Expected Msg 102 or 156, got {num}");
+    }
+
+    [TestMethod]
+    public void Delay_CastOperand_SyntaxError()
+        => _ = Throws<DbException>(
+            () => _ = new Simulation().ExecuteNonQuery(
+                "waitfor delay cast('00:00:00.050' as time)"));
+
+    [TestMethod]
+    public void WaitforTime_NotSupported()
+        => _ = Throws<NotSupportedException>(
+            () => _ = new Simulation().ExecuteNonQuery("waitfor time '23:59:59'"));
+
+    [TestMethod]
+    public void Delay_BetweenSelects_BothRun()
+    {
+        using var reader = new Simulation().ExecuteReader(
+            "select 'before' as v; waitfor delay '00:00:00'; select 'after' as v");
+        IsTrue(reader.Read());
+        AreEqual("before", reader.GetString(0));
+        IsTrue(reader.NextResult());
+        IsTrue(reader.Read());
+        AreEqual("after", reader.GetString(0));
+    }
+
+    [TestMethod]
+    public void Delay_InWhile_RunsEachIteration()
+    {
+        // Three iterations, each waiting 0 — exercises dispatch in the loop
+        // body. The loop completes in nominal time.
+        var start = Stopwatch.GetTimestamp();
+        _ = new Simulation().ExecuteNonQuery("""
+            declare @i int = 0;
+            while @i < 3
+            begin
+                set @i = @i + 1;
+                waitfor delay '00:00:00';
+            end
+            """);
+        var elapsed = Stopwatch.GetElapsedTime(start);
+        IsLessThan(500, elapsed.TotalMilliseconds,
+            $"Expected fast loop, got {elapsed.TotalMilliseconds}ms");
+    }
+}
diff --git a/SqlServerSimulator/Errors/SimulatedSqlException.QueryErrors.cs b/SqlServerSimulator/Errors/SimulatedSqlException.QueryErrors.cs
@@ -326,4 +326,26 @@ internal static SimulatedSqlException IntegerIndexNotAllowedInOrderedAggregate()
     /// </summary>
     internal static SimulatedSqlException AllResultsInCaseAreNull() =>
         new("At least one of the result expressions in a CASE specification must be an expression other than the NULL constant.", 8133, 16, 1);
+
+    /// <summary>
+    /// Mimics SQL Server's Msg 148 — the string operand of <c>WAITFOR DELAY</c>
+    /// (or <c>WAITFOR TIME</c>, not modeled) wasn't a valid time format. Probe-
+    /// confirmed against SQL Server 2025 (2026-05-11): Class 15, State 1,
+    /// verbatim wording. Valid format is <c>HH:MM:SS[.fff]</c> with hours
+    /// 0-23 and no leading sign. Negative, day-component, and over-24h
+    /// strings all surface this same error.
+    /// </summary>
+    internal static SimulatedSqlException IncorrectWaitForTimeSyntax(string value) =>
+        new($"Incorrect time syntax in time string '{value}' used with WAITFOR.", 148, 15, 1);
+
+    /// <summary>
+    /// Mimics SQL Server's Msg 9815 — the operand of <c>WAITFOR DELAY</c>
+    /// (or <c>WAITFOR TIME</c>) is a variable typed as <c>time</c>. Real
+    /// SQL Server reserves the operand for char/varchar/nchar/nvarchar
+    /// values; the <c>time</c> type is paradoxically rejected. Probe-
+    /// confirmed against SQL Server 2025 (2026-05-11): Class 16, State 0,
+    /// verbatim wording.
+    /// </summary>
+    internal static SimulatedSqlException WaitForCannotBeTimeType() =>
+        new("Waitfor delay and waitfor time cannot be of type time.", 9815, 16, 0);
 }
diff --git a/SqlServerSimulator/Parser/Selection.cs b/SqlServerSimulator/Parser/Selection.cs
@@ -423,7 +423,7 @@ or Keyword.Merge or Keyword.Begin or Keyword.Commit or Keyword.Rollback
                         or Keyword.Save or Keyword.Create or Keyword.Drop or Keyword.Alter or Keyword.Dbcc
                         or Keyword.Set or Keyword.Declare or Keyword.If or Keyword.Else or Keyword.End
                         or Keyword.While or Keyword.Break or Keyword.Continue or Keyword.Return
-                        or Keyword.Print
+                        or Keyword.Print or Keyword.WaitFor
                 } when depth == 0:
                     goto ExitWhileTokenLoop;
 
@@ -567,7 +567,7 @@ or Keyword.Merge or Keyword.Begin or Keyword.Commit or Keyword.Rollback
                         or Keyword.Save or Keyword.Create or Keyword.Drop or Keyword.Alter or Keyword.Dbcc
                         or Keyword.Set or Keyword.Declare or Keyword.If or Keyword.Else or Keyword.End
                         or Keyword.While or Keyword.Break or Keyword.Continue or Keyword.Return
-                        or Keyword.Print
+                        or Keyword.Print or Keyword.WaitFor
                 } when depth == 0:
                     goto ExitWhileTokenLoop;
 
diff --git a/SqlServerSimulator/Simulation/Simulation.WaitFor.cs b/SqlServerSimulator/Simulation/Simulation.WaitFor.cs
@@ -0,0 +1,116 @@
+using System.Globalization;
+using SqlServerSimulator.Parser;
+using SqlServerSimulator.Parser.Tokens;
+using SqlServerSimulator.Storage;
+
+namespace SqlServerSimulator;
+
+partial class Simulation
+{
+    /// <summary>
+    /// Parses and runs <c>WAITFOR DELAY '&lt;time&gt;'</c> or
+    /// <c>WAITFOR DELAY @variable</c>. Probed against SQL Server 2025
+    /// (2026-05-11): the operand grammar is strict — only a string literal
+    /// or a <c>@variable</c> reference; <c>cast(...)</c>, integer literals,
+    /// the bare <c>NULL</c> literal, and a <c>time</c>-typed variable are
+    /// all rejected by real SQL Server (Msg 102 / Msg 156 / Msg 9815),
+    /// and the simulator inherits that rejection by not parsing those
+    /// shapes. <c>WAITFOR TIME</c> (the absolute-time form) raises
+    /// <see cref="NotSupportedException"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Time format: <c>HH:MM:SS[.fff]</c> (or <c>HH:MM</c>) with hours 0-23
+    /// and no sign or day component. Bad format → Msg 148. An empty string
+    /// or a NULL-valued variable is silently accepted as a zero delay
+    /// (probe-confirmed: <c>waitfor delay ''</c> and a NULL-valued varchar
+    /// both succeed without sleeping).
+    /// </para>
+    /// <para>
+    /// Sleep mechanism: <see cref="Thread.Sleep(TimeSpan)"/> on the calling
+    /// thread, matching real SQL Server's "blocks the connection" semantics.
+    /// The simulator's dispatch is synchronous; an <c>ExecuteReaderAsync</c>
+    /// caller's <c>CancellationToken</c> isn't threaded into the sleep —
+    /// documented gap in CLAUDE.md. <c>@@ROWCOUNT</c> resets to 0
+    /// (probe-confirmed; applied by the dispatcher after this parser returns).
+    /// Skip-mode (un-taken IF, after BREAK/CONTINUE/RETURN) suppresses the
+    /// sleep entirely.
+    /// </para>
+    /// </remarks>
+    private static void ParseWaitForStatement(BatchContext batch)
+    {
+        var context = batch.Parser;
+        context.MoveNextRequired(); // consume WAITFOR
+
+        // DELAY and TIME are contextual keywords (not in the reserved list),
+        // tokenized as UnquotedString. WAITFOR TIME isn't modeled — it's an
+        // absolute-time wait whose primary use case is scheduling, which is
+        // out of scope for the simulator.
+        if (context.Token is not UnquotedString verb)
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+        if (verb.Span.Equals("TIME", StringComparison.OrdinalIgnoreCase))
+            throw new NotSupportedException("WAITFOR TIME (absolute-time wait) isn't modeled — WAITFOR DELAY is.");
+        if (!verb.Span.Equals("DELAY", StringComparison.OrdinalIgnoreCase))
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+
+        context.MoveNextRequired(); // consume DELAY
+
+        // Capture the raw string operand. The grammar is strict: literal or
+        // @-prefixed variable reference only. Anything else (cast, integer
+        // literal, bare NULL, paren-expr) falls through to Msg 102 / Msg 156
+        // from real SQL Server; the simulator routes them all through the
+        // existing SyntaxErrorNear path which produces Msg 102.
+        string? operandText;
+        switch (context.Token)
+        {
+            case Literal lit when lit.Value.Type is VarcharSqlType or NVarcharSqlType:
+                operandText = lit.Value.IsNull ? null : lit.Value.AsString;
+                break;
+
+            case AtPrefixedString variableToken:
+                {
+                    var slot = batch.GetVariableSlot(variableToken.Value);
+                    if (slot.DeclaredType is TimeSqlType)
+                        throw SimulatedSqlException.WaitForCannotBeTimeType();
+                    operandText = slot.Value.IsNull ? null : slot.Value.CoerceTo(SqlType.Varchar).AsString;
+                    break;
+                }
+
+            default:
+                throw SimulatedSqlException.SyntaxErrorNear(context);
+        }
+
+        context.MoveNextOptional(); // consume the operand token
+
+        if (batch.IsSkipping)
+            return;
+
+        // Probe-confirmed: NULL via variable, and empty string, both succeed
+        // silently with zero delay.
+        if (string.IsNullOrEmpty(operandText))
+            return;
+
+        if (!TryParseWaitForTime(operandText, out var delay))
+            throw SimulatedSqlException.IncorrectWaitForTimeSyntax(operandText);
+
+        if (delay.Ticks > 0)
+            Thread.Sleep(delay);
+    }
+
+    private static readonly string[] waitForTimeFormats =
+    [
+        @"hh\:mm\:ss",
+        @"hh\:mm\:ss\.f",
+        @"hh\:mm\:ss\.ff",
+        @"hh\:mm\:ss\.fff",
+        @"hh\:mm\:ss\.ffff",
+        @"hh\:mm\:ss\.fffff",
+        @"hh\:mm\:ss\.ffffff",
+        @"hh\:mm\:ss\.fffffff",
+        @"hh\:mm",
+    ];
+
+    private static bool TryParseWaitForTime(string value, out TimeSpan result) =>
+        TimeSpan.TryParseExact(value, waitForTimeFormats, CultureInfo.InvariantCulture, out result)
+            && result.Ticks is >= 0 and < TimeSpan.TicksPerDay;
+}
diff --git a/SqlServerSimulator/Simulation/Simulation.cs b/SqlServerSimulator/Simulation/Simulation.cs
