docs: add note about time.sleep (microsoft#698)

mxschmitt · web-flow · commit cfc1030a69d1 · 2021-05-18T23:43:40.000+02:00
diff --git a/README.md b/README.md
@@ -22,6 +22,7 @@ Headless execution is supported for all browsers on all platforms.
   - [Mobile and geolocation](#mobile-and-geolocation)
   - [Evaluate JS in browser](#evaluate-js-in-browser)
   - [Intercept network requests](#intercept-network-requests)
+- [Known issues](#known-issues)
 - [Documentation](#documentation)
 
 ## Usage - pip
@@ -298,6 +299,12 @@ asyncio.run(main())
 
 </details>
 
+## Known issues
+
+### `time.sleep()` leads to outdated state
+
+You need to use `page.wait_for_timeout(5000)` instead of `time.sleep()`. It is better to not wait for a timeout at all, but sometimes it is useful for debugging. In these cases, use our wait method instead of the system one. This is because we internally rely on asynchronous operations and when using `time.sleep(5)` they can't get processed correctly.
+
 ## Documentation
 
 Check out our [new documentation site](https://playwright.dev/python/docs/intro)!
