Merge pull request #1133 from japgolly/test_utils_deprecation

Deprecate `ReactTestUtils`

Author: japgolly

doc/TESTING.md

@@ -49,7 +49,8 @@ Read through the following for how to test with `ReactTestUtils`.
 
 ```scala
 import japgolly.scalajs.react._
-import japgolly.scalajs.react.test._
+import japgolly.scalajs.react.test.ReactTestUtils
+import japgolly.scalajs.react.testing_library.dom.Simulate
 import japgolly.scalajs.react.vdom.html_<^._
 import utest._
 

doc/changelog/3.0.0.md

@@ -1,6 +1,6 @@
 # 3.0.0
 
-### New
+## New
 
 - React 18 support
   - List of implemented features is here: https://github.com/japgolly/scalajs-react/issues/1057
@@ -27,7 +27,7 @@
 
 - `Renderable` typeclass for anything that React can render
 
-### Other Changes
+## Other Changes
 
 - Allow calling `useCallback*` with sync functions that return a value.
 
@@ -41,7 +41,7 @@
 - `TriStateCheckbox` no longer uses `Reusability.shouldComponentUpdate`, therefore
   the fourth argument to its props is no longer wrapped in `Reusable`.
 
-### Deprecated
+## Deprecated
 
 - Anything deprecated by React 18 is now deprecated in Scala
 
@@ -51,7 +51,7 @@
 
 - `ReactTestUtils` is now `LegacyReactTestUtils` and deprecated
 
-### Upgrades
+## Upgrades
 
 - Cats 2.13.0
 - CatsEffect 3.6.3
@@ -62,44 +62,79 @@
 - ScalaJsDom 2.8.1
 - Sourcecode 0.4.4
 
-### Migration
+## Migration
 
-- Run this to switch from `{ => Legacy}ReactTestUtils`, and if you were on the betas `ReactTestUtils{2 => }`:
+### `jsDependencies`
 
-    ```sh
-    find . -type f -name '*.scala' -exec perl -pi -e '
-      s/\bReactTestUtils\b/LegacyReactTestUtils/g;
-      s/\bReactTestUtils2\b/ReactTestUtils/g;
-    ' {} +
-    ```
+To upgrade when using `jsDependencies`, make your sbt config look like this (comments for clarity)
 
-- To upgrade when using `jsDependencies`, make your sbt config look like this (comments for clarity)
+```scala
+// Required for React 18.3.1
+dependencyOverrides += "org.webjars.npm" % "scheduler" % "0.22.0",
 
-  ```scala
-  // Required for React 18.0.0
-  dependencyOverrides += "org.webjars.npm" % "scheduler" % "0.22.0",
-
-  jsDependencies ++= Seq(
-
-    // Polyfill required for React 18.0.0
-    "org.webjars.npm" % "fast-text-encoding" % "1.0.3" / "text.js" minified "text.min.js"
-
-    "org.webjars.npm" % "react" % "18.0.0"
-      /         "umd/react.development.js"
-      minified  "umd/react.production.min.js"
-      dependsOn "text.js" // <-- Load the fast-text-encoding polyfill before loading React itself
-      commonJSName "React",
-
-    "org.webjars.npm" % "react-dom" % "18.0.0"
-      /         "umd/react-dom.development.js"
-      minified  "umd/react-dom.production.min.js"
-      dependsOn "umd/react.development.js"
-      commonJSName "ReactDOM",
-
-    "org.webjars.npm" % "react-dom" % "18.0.0"
-      /         "umd/react-dom-server.browser.development.js"
-      minified  "umd/react-dom-server.browser.production.min.js"
-      dependsOn "umd/react-dom.development.js"
-      commonJSName "ReactDOMServer",
-  ),
-  ```
+jsDependencies ++= Seq(
+
+  // Polyfill required for React 18.3.1
+  "org.webjars.npm" % "fast-text-encoding" % "1.0.6" / "1.0.6/text.min.js" minified "text.min.js"
+
+  "org.webjars.npm" % "react" % "18.3.1"
+    /         "umd/react.development.js"
+    minified  "umd/react.production.min.js"
+    dependsOn "text.js" // <-- Load the fast-text-encoding polyfill before loading React itself
+    commonJSName "React",
+
+  "org.webjars.npm" % "react-dom" % "18.3.1"
+    /         "umd/react-dom.development.js"
+    minified  "umd/react-dom.production.min.js"
+    dependsOn "umd/react.development.js"
+    commonJSName "ReactDOM",
+
+  "org.webjars.npm" % "react-dom" % "18.3.1"
+    /         "umd/react-dom-server.browser.development.js"
+    minified  "umd/react-dom-server.browser.production.min.js"
+    dependsOn "umd/react-dom.development.js"
+    commonJSName "ReactDOMServer",
+),
+```
+
+### `ReactTestUtils`
+
+Run this to switch from `{ => Legacy}ReactTestUtils`, and if you were on the betas `ReactTestUtils{2 => }`:
+
+```sh
+find . -type f -name '*.scala' -exec perl -pi -e '
+  s/\bReactTestUtils\b/LegacyReactTestUtils/g;
+  s/\bReactTestUtils2\b/ReactTestUtils/g;
+' {} +
+```
+
+### `Simulate`, `SimEvent`, `Simulation`
+
+React has removed `Simulate` as of React v19. It is deprecated in React v18.
+
+React now recommends using [React Testing Library](https://testing-library.com/react) instead.
+There is no Scala.js facade for it, and even if there was it wouldn't be a drop-in replacement.
+
+As a band-aid solution, there is now a new scalajs-react module called `testing_library-dom`
+that builds on `@testing-library/dom` and
+provides a subset of `Simulate`, `SimEvent`, `Simulation` under the
+`japgolly.scalajs.react.testing_library.dom` package.
+
+Unfortunately some types of events like `Simulate.change` do not fire and thus have been removed from the API.
+
+Add this to your sbt:
+
+```scala
+libraryDependencies += "com.github.japgolly.scalajs-react" %%% "testing_library-dom" % "3.0.0" % Test
+
+jsDependencies += "org.webjars.npm" % "testing-library__dom" % "10.4.1" /
+                    "dom.umd.js" commonJSName "TestingLibraryDom" % Test
+```
+
+and to use it:
+
+```scala
+import japgolly.scalajs.react.testing_library.dom.Simulate
+
+// Simulate.click(domNode)
+```

library/build.sbt

@@ -22,6 +22,7 @@ val ghpages               = ScalaJsReact.ghpages
 val ghpagesMacros         = ScalaJsReact.ghpagesMacros
 val root                  = ScalaJsReact.root
 val scalafixRules         = ScalaJsReact.scalafixRules
+val testingLibraryDom     = ScalaJsReact.testingLibraryDom
 val tests                 = ScalaJsReact.tests
 val testsDep              = ScalaJsReact.testsDep
 val testUtilMacros        = ScalaJsReact.testUtilMacros

library/facadeTest/src/main/scala/japgolly/scalajs/react/test/facade/ReactTestUtils.scala

@@ -28,7 +28,7 @@ trait ReactTestUtils extends js.Object {
     *
     * This helps make your tests run closer to what real users would experience when using your application.
     */
-  @deprecated("Use React.act", "3.0.0")
+  @deprecated("Use React.act", "3.0.0 / React v18")
   final def act(body: js.Function0[Any]): js.Thenable[Unit] = js.native
 
   /** When writing UI tests, tasks like rendering, user events, or data fetching can be considered as "units" of
@@ -45,69 +45,83 @@ trait ReactTestUtils extends js.Object {
     * This helps make your tests run closer to what real users would experience when using your application.
     */
   @JSName("act")
-  @deprecated("Use React.actAsync", "3.0.0")
+  @deprecated("Use React.actAsync", "3.0.0 / React v18")
   final def actAsync(body: js.Function0[js.Thenable[Any]]): js.Thenable[Unit] = js.native
 
   /** Render a component into a detached DOM node in the document. This function requires a DOM. */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def renderIntoDocument(element: React.Element): React.ComponentUntyped | Null = js.native
 
   /**
    * Pass a mocked component module to this method to augment it with useful methods that allow it to be used as a dummy
    * React component. Instead of rendering as usual, the component will become a simple <div> (or other tag if
    * mockTagName is provided) containing any provided children.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def mockComponent[P <: js.Object, S <: js.Object](c: React.ComponentClass[P, S], mockTagName: String = js.native): React.ComponentClass[P, S] = js.native
 
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final type Mounted = React.ComponentUntyped
 
   /** Returns true if instance is an instance of a React componentClass. */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def isComponentOfType(instance: React.Element, c: React.ComponentClassUntyped): Boolean = js.native
 
   /** Returns true if instance is a DOM component (such as a &lt;div&gt; or &lt;span&gt;). */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def isDOMComponent(instance: React.Element): Boolean = js.native
 
   /** Returns true if instance is a composite component (created with React.createClass()) */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def isCompositeComponent(instance: React.Element): Boolean = js.native
 
   /** The combination of [[isComponentOfType()]] and [[isCompositeComponent()]]. */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def isCompositeComponentWithType(instance: React.Element, c: React.ComponentClassUntyped): Boolean = js.native
 
   /**
    * Traverse all components in tree and accumulate all components where test(component) is true.
    * This is not that useful on its own, but it's used as a primitive for other test utils.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def findAllInRenderedTree(tree: Mounted, test: js.Function1[Mounted, Boolean]): js.Array[Mounted] = js.native
 
   /**
    * Finds all instance of components in the rendered tree that are DOM components with the class name
    * matching className.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def scryRenderedDOMComponentsWithClass(tree: Mounted, className: String): js.Array[Mounted] = js.native
 
   /**
    * Like [[scryRenderedDOMComponentsWithClass()]] but expects there to be one result, and returns that one result, or
    * throws exception if there is any other number of matches besides one.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def findRenderedDOMComponentWithClass(tree: Mounted, className: String): Mounted = js.native
 
   /**
    * Finds all instance of components in the rendered tree that are DOM components with the tag name
    * matching tagName.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def scryRenderedDOMComponentsWithTag(tree: Mounted, tagName: String): js.Array[Mounted] = js.native
 
   /**
    * Like [[scryRenderedDOMComponentsWithTag()]] but expects there to be one result, and returns that one result, or
    * throws exception if there is any other number of matches besides one.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def findRenderedDOMComponentWithTag(tree: Mounted, tagName: String): Mounted = js.native
 
   /** Finds all instances of components with type equal to componentClass. */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def scryRenderedComponentsWithType(tree: Mounted, c: React.ComponentClassUntyped): js.Array[Mounted] = js.native
 
   /**
    * Same as [[scryRenderedComponentsWithType()]] but expects there to be one result and returns that one result, or throws
    * exception if there is any other number of matches besides one.
    */
+  @deprecated("Deprecated in favour of https://testing-library.com/react", "3.0.0 / React v18")
   final def findRenderedComponentWithType(tree: Mounted, c: React.ComponentClassUntyped): Mounted = js.native
 }

library/project/Build.scala

@@ -35,6 +35,7 @@ object ScalaJsReact {
       ghpages,
       ghpagesMacros,
       scalafixRules,
+      testingLibraryDom,
       testsDep,
       tests,
       testUtilMacros,
@@ -210,9 +211,18 @@ object ScalaJsReact {
     )
     .configure(conditionallyDisable) // keep this last
 
+  lazy val testingLibraryDom = project
+    .dependsOn(testUtil)
+    .configure(commonSettings, publicationSettings, hasNoTests)
+    .settings(
+      moduleName := "testing_library-dom",
+      libraryDependencies += Dep.scalaJsDom.value,
+    )
+
   lazy val tests = project
     .dependsOn(testUtil, coreExtCatsEffect, extraExtMonocle3)
     .dependsOn(coreBundleCallback) // Low priority
+    .dependsOn(testingLibraryDom % Test)
     .configure(commonSettings, preventPublication, utestSettings, addReactJsDependencies(Test))
     .settings(
       Test / scalacOptions -= "-Xlint:adapted-args",
@@ -230,6 +240,7 @@ object ScalaJsReact {
         (ProvidedJS / "component-es6.js" dependsOn Dep.reactDom.dev) % Test,
         (ProvidedJS / "component-fn.js"  dependsOn Dep.reactDom.dev) % Test,
         (ProvidedJS / "forward-ref.js"   dependsOn Dep.reactDom.dev) % Test,
+        Dep.testingLibraryDomJs.value % Test,
       ),
     )
 

library/project/Dependencies.scala

@@ -18,6 +18,7 @@ object Dependencies {
     val scala3                = "3.3.0"
     val scalaJsDom            = "2.8.1"
     val sourcecode            = "0.4.4"
+    val testingLibraryDomJs   = "10.4.1"
 
     // Internal
     val betterMonadicFor      = "0.3.1"
@@ -75,9 +76,12 @@ object Dependencies {
     val reactDom          = ReactArtifact("react-dom")
     val reactDomServer    = ReactArtifact("react-dom-server.browser")
     val reactDoutestUtils = ReactArtifact("react-dom-test-utils")
+
+    val testingLibraryDomJs = Def.setting("org.webjars.npm" % "testing-library__dom" % Ver.testingLibraryDomJs /
+      "dom.umd.js" commonJSName "TestingLibraryDom")
   }
 
-  def fastTextEncodingJs = "text.min.js" // 1.0.6 webjar only contains minified version
+  def fastTextEncodingJs = s"${Ver.fastTextEncoding}/text.min.js" // 1.0.6 webjar only contains minified version
 
   def globalDependencyOverrides = Def.setting(Seq(
     Dep.scalaJsDom.value,

library/testUtil/src/main/scala/japgolly/scalajs/react/test/ReactEventType.scala

@@ -28,8 +28,8 @@ object ReactEventType {
       // val target          : DOMEventTarget = js.native
       // val `type`          : String         = js.native
       js.Dynamic.literal(
-        bubbles          = false,
-        cancelable       = false,
+        bubbles          = true,
+        cancelable       = true,
         defaultPrevented = false,
         isTrusted        = false,
         timeStamp        = System.currentTimeMillis().toDouble,
@@ -172,4 +172,4 @@ object ReactEventType {
         deltaMode = 0, // The delta values are specified in pixels
       ))
   }
-}
+}

library/testUtil/src/main/scala/japgolly/scalajs/react/test/ReactTestUtils.scala

@@ -34,7 +34,6 @@ trait ReactTestUtils extends japgolly.scalajs.react.test.internal.ReactTestUtilE
   private val reactRaw = japgolly.scalajs.react.facade.React
 
   type Unmounted = GenericComponent.Unmounted[_, Unit]
-
   type CompType = GenericComponent.ComponentRaw {type Raw <: japgolly.scalajs.react.facade.React.ComponentClassUntyped }
 
   // ===================================================================================================================

library/testUtil/src/main/scala/japgolly/scalajs/react/test/SimEvent.scala

@@ -7,6 +7,7 @@ import scala.scalajs.js.Dynamic
 // NOTE: Do not use UndefOr for arguments below; undefined causes Phantom-bloody-JS to crash.
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
+@deprecated("See the 3.0.0 changelog for migration details", "3.0.0 / React v18")
 object SimEvent {
 
   case class Change(value           : String              = "",

library/testUtil/src/main/scala/japgolly/scalajs/react/test/Simulate.scala

@@ -5,6 +5,7 @@ import japgolly.scalajs.react.test.facade
 import scala.scalajs.js
 
 /** https://reactjs.org/docs/test-utils.html#simulate */
+@deprecated("See the 3.0.0 changelog for migration details", "3.0.0 / React v18")
 object Simulate {
   import ReactEventType._