Introduce gwen.logLevel.deprecations to control how deprecations are reported

Author: bjuric

CHANGELOG

@@ -1,3 +1,12 @@
+3.63.0
+======
+19 September 2024
+- Introduce `gwen.logLevel.deprecations` to control how deprecations are reported.
+  - Supported values include:
+    - `warn` to log deprecations as warnings (default)
+    - `error` to raise and report deprecations as errors
+    - `none` to suppress logging or reporting of deprecation messages (no operation)
+
 3.62.0
 ======
 18 September 2024

build.sbt

@@ -1,7 +1,7 @@
 enablePlugins(GitVersioning)
 
 // gwen core version
-val gwenVersion = "3.62.0"
+val gwenVersion = "3.63.0"
 
 git.baseVersion := gwenVersion
 git.useGitDescribe := true

src/main/resources/gwen.conf

@@ -112,6 +112,9 @@ gwen {
     }
     mode = "declarative"          # declarative|imperative
   }
+  logLevel {
+    deprecations = "warn"         # warn|error|none
+  }
   mask {
     char = "*"
   }

src/main/scala/gwen/core/GwenOptions.scala

@@ -163,7 +163,7 @@ object GwenOptions {
 
       opt[String]('p', "properties") action {
         (ps, c) =>
-          Deprecation.warn("CLI option", "-p|--properties", Some("-c|--conf"))
+          Deprecation.log("CLI option", "-p|--properties", Some("-c|--conf"))
           c.copy(settingsFiles = c.settingsFiles ++ ps.split(",").toList.map(new File(_)))
       } validate { ps =>
         ((ps.split(",") flatMap { f =>
@@ -184,7 +184,7 @@ object GwenOptions {
         (fs, c) =>
           val formats = fs.split(",").toList.map(f => ReportFormat.valueOf(f))
           formats.find(_ == ReportFormat.rp) foreach { format =>
-            Deprecation.warn("Report Portal option", s"-f|--format = $format", None)
+            Deprecation.log("Report Portal option", s"-f|--format = $format", None)
           }
           c.copy(reportFormats = formats)
       } valueName "reports" text s"""|Report formats to include in output (comma separated)

src/main/scala/gwen/core/GwenSettings.scala

@@ -23,6 +23,7 @@ import gwen.core.state.StateLevel
 import scala.util.Try
 
 import java.io.File
+import java.util.logging.Level
 
 /**
   * Provides access to all Gwen settings.
@@ -57,6 +58,7 @@ object GwenSettings {
     `gwen.state.level`
     `gwen.video.dir`
     `gwen.video.timeoutSecs`
+    `gwen.logLevel.deprecations`
   }
 
   /**
@@ -373,4 +375,25 @@ object GwenSettings {
       Settings.getBoolean("gwen.error.messages.inline.locators")
   }
 
+  /**
+    * Provides access to the `gwen.behavior.rules` setting used to determine whether strict,
+    * or lenient rules around Given-When-Then usage should be enforced in features (default value is
+    * `strict`). When strict, scenarios and backgrounds must contain Given-When-Then ordered steps
+    * and Given steps set context, When steps must perform actions, and Then or But steps must perform
+    * assertions. When `leneient` no behavioral rules are enforced. Note that `gwen.behavior.rules` is
+    * an alias for this setting.
+    */
+  def `gwen.logLevel.deprecations`: Level = {
+    Settings.getOpt("gwen.logLevel.deprecations") map { level => 
+      level match {
+        case "warn" => Level.WARNING
+        case "error" => Level.SEVERE
+        case "none" => Level.OFF
+        case _ => Errors.invalidSettingError("gwen.logLevel.deprecations", level, "Valid value are warn|error|none")
+      }
+    } getOrElse {
+      Level.WARNING
+    }
+  }
+
 }

src/main/scala/gwen/core/Predefs.scala

@@ -55,6 +55,7 @@ import javax.xml.transform.TransformerFactory
 import javax.xml.transform.stream.StreamResult
 import javax.xml.transform.stream.StreamSource
 import javax.xml.transform.OutputKeys
+import java.util.logging.Level
 
 /** Predefs and extension methods avaiable wherever this page is imported. */
 
@@ -456,18 +457,26 @@ object UUIDGenerator {
 }
 
 object Deprecation extends LazyLogging {
-  def warn(category: String, oldWay: String, newWayOpt: Option[String]): Unit = {
-    println(
-      s"""|
-          |WARNING: $category is deprecated and will be unsupported in next major Gwen 4 release
-          |${createMsg(category, oldWay, newWayOpt)}
-          |""".stripMargin
-    )
+  import java.util.logging.Level
+  import org.fusesource.jansi.Ansi._
+  def log(category: String, oldWay: String, newWayOpt: Option[String]): Unit = {
+    val level = GwenSettings.`gwen.logLevel.deprecations`
+    val msg = s"""|${if (level == Level.WARNING) s"$level: " else ""}$category is deprecated and will not be unsupported in next major release
+                  |${createMsg(category, oldWay, newWayOpt)}
+                  |""".stripMargin
+    level match {
+      case Level.WARNING => 
+        val colors = ConsoleColors.isEnabled
+        println(s"\n${if (colors) ansi.fg(Color.YELLOW) else ""}$msg${if (colors) ansi.reset else ""}")
+      case Level.SEVERE => 
+        Errors.deprecatedError(msg)
+      case _ => // noop
+    }
   }
+
   def fail(category: String, oldWay: String, newWayOpt: Option[String]): Unit = {
     Errors.deprecatedError(
-      s"""|
-          |$category is deprecated and no longer supported
+      s"""|$category is deprecated and no longer supported
           |${createMsg(category, oldWay, newWayOpt)}
           |""".stripMargin
     )

src/main/scala/gwen/core/eval/EvalEngine.scala

@@ -82,38 +82,38 @@ abstract class EvalEngine[T <: EvalContext] extends NodeEventDispatcher with Uni
       case r"""(.+)$doStep if(?:(?!\bif\b))( not)?$negation (.+)$condition""" if !condition.contains('"') =>
         Some(new IfCondition(doStep, condition, Option(negation).isDefined, defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined using no delay and (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" =>
-        Deprecation.warn("Step variant", s"using no delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('0s') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
+        Deprecation.log("Overloaded step", s"using no delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('0s') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, Duration.Zero, Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined using no delay""" =>
-        Deprecation.warn("Step variant", s"using no delay", Some(s"@Delay('0s') annotation"))
+        Deprecation.log("Overloaded step", s"using no delay", Some(s"@Delay('0s') annotation"))
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, Duration.Zero, step.timeoutOpt.getOrElse(defaultRepeatTimeout(defaultRepeatDelay)), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined using (.+?)$delayPeriod (second|millisecond)$delayUnit delay and (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" if doStep != "I wait" =>
-        Deprecation.warn("Step variant", s"using $delayPeriod $delayUnit delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
+        Deprecation.log("Overloaded step", s"using $delayPeriod $delayUnit delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, Duration(delayPeriod.toLong, delayUnit), Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined using (.+?)$delayPeriod (second|millisecond)$delayUnit delay""" if doStep != "I wait" =>
-        Deprecation.warn("Step variant", s"using $delayPeriod $delayUnit delay", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') annotation"))
+        Deprecation.log("Overloaded step", s"using $delayPeriod $delayUnit delay", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') annotation"))
         val delayDuration = Duration(delayPeriod.toLong, delayUnit)
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, delayDuration, defaultRepeatTimeout(delayDuration), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined using (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" if doStep != "I wait" =>
-        Deprecation.warn("Step variant", s"using $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotation"))
+        Deprecation.log("Overloaded step", s"using $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotation"))
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, step.delayOpt.getOrElse(defaultRepeatDelay), Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$attribute is( not)?$negation defined""" if (doStep != "I wait" && !step.expression.matches(""".*".*(until|while).*".*""")) =>
         Some(new RepeatIfDefined(doStep, operation, attribute, Option(negation).isDefined, step.delayOpt.getOrElse(defaultRepeatDelay), step.timeoutOpt.getOrElse(defaultRepeatTimeout(defaultRepeatDelay)), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition using no delay and (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" if !condition.contains('"') =>
-        Deprecation.warn("Step variant", s"using no delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('0s') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
+        Deprecation.log("Overloaded step", s"using no delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('0s') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
         Some(new RepeatJS(doStep, operation, condition, Duration.Zero, Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition using no delay""" if !condition.contains('"') =>
-        Deprecation.warn("Step variant", s"using no delay", Some(s"@Delay('0s') annotation"))
+        Deprecation.log("Overloaded step", s"using no delay", Some(s"@Delay('0s') annotation"))
         Some(new RepeatJS(doStep, operation, condition, Duration.Zero, step.timeoutOpt.getOrElse(defaultRepeatTimeout(defaultRepeatDelay)), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition using (.+?)$delayPeriod (second|millisecond)$delayUnit delay and (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" if doStep != "I wait" && !condition.contains('"') =>
-        Deprecation.warn("Step variant", s"using $delayPeriod $delayUnit delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
+        Deprecation.log("Overloaded step", s"using $delayPeriod $delayUnit delay and $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') @Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotations"))
         Some(new RepeatJS(doStep, operation, condition, Duration(delayPeriod.toLong, delayUnit), Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition using (.+?)$delayPeriod (second|millisecond)$delayUnit delay""" if doStep != "I wait" && !condition.contains('"') =>
-        Deprecation.warn("Step variant", s"using $delayPeriod $delayUnit delay", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') annotation"))
+        Deprecation.log("Overloaded step", s"using $delayPeriod $delayUnit delay", Some(s"@Delay('$delayPeriod${Map("second" -> "s", "millisecond" -> "ms")(delayUnit)}') annotation"))
         val delayDuration = Duration(delayPeriod.toLong, delayUnit)
         Some(new RepeatJS(doStep, operation, condition, delayDuration, defaultRepeatTimeout(delayDuration), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition using (.+?)$timeoutPeriod (minute|second|millisecond)$timeoutUnit (timeout|wait)$timeoutLiteral""" if doStep != "I wait" && !condition.contains('"') =>
-        Deprecation.warn("Step variant", s"using $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotation"))
+        Deprecation.log("Overloaded step", s"using $timeoutPeriod $timeoutUnit $timeoutLiteral", Some(s"@Timeout('$timeoutPeriod${Map("minute" -> "m", "second" -> "s", "millisecond" -> "ms")(timeoutUnit)}') annotation"))
         Some(new RepeatJS(doStep, operation, condition, step.delayOpt.getOrElse(defaultRepeatDelay), Duration(timeoutPeriod.toLong, timeoutUnit), defaultConditionTimeoutSecs, this))
       case r"""(.+?)$doStep (until|while)$operation (.+?)$condition""" if (doStep != "I wait" && !condition.contains('"') && !step.expression.matches(""".*".*(until|while).*".*""")) =>
         Some(new RepeatJS(doStep, operation, condition, step.delayOpt.getOrElse(defaultRepeatDelay), step.timeoutOpt.getOrElse(defaultRepeatTimeout(defaultRepeatDelay)), defaultConditionTimeoutSecs, this))

src/test/scala/gwen/core/GwenSettingsTest.scala

@@ -27,6 +27,7 @@ import gwen.core.report.rp.RPSettings
 import gwen.core.state.StateLevel
 
 import org.scalatest.matchers.should.Matchers
+import java.util.logging.Level
 
 class GwenSettingsTest extends BaseTest with Matchers {
 
@@ -66,6 +67,7 @@ class GwenSettingsTest extends BaseTest with Matchers {
       GwenSettings.`gwen.video.timeoutSecs` should be (10)
       GwenSettings.`gwen.dryRun.limit.tableData.outline.examples.records` should be (Integer.MAX_VALUE)
       GwenSettings.`gwen.error.messages.inline.locators` should be (false)
+      GwenSettings.`gwen.logLevel.deprecations` should be (Level.WARNING)
     }
   }