From 09e101c7ae30a1cffc5d382ed88c06bcb478ab9e Mon Sep 17 00:00:00 2001
From: Kian-Meng Ang <kianmeng@cpan.org>
Date: Mon, 1 Jul 2024 19:07:56 +0800
Subject: [PATCH] Rewrite the contributing and test docs

This PR updates the console markups so we can we can quickly click and
copy them.
---
 README.md | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d5117d8d..f2b1d4b5 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,11 @@ defp deps do
 end
 ```
 
-Then, run `$ mix deps.get`.
+Then, run:
+
+```sh
+mix deps.get
+```
 
 ## Usage
 
@@ -106,13 +110,30 @@ Mint is a low-level client. If you need higher-level features such as connection
 
 If you wish to contribute, check out the [issue list][issues] and let us know what you want to work on, so that we can discuss it and reduce duplicate work.
 
-Tests are organized with tags. Integration tests that hit real websites over the internet are tagged with `:requires_internet_connection`. Proxy tests are tagged with `:proxy` and require that you run `DOCKER_USER="$UID:$GID" docker-compose up` from the Mint root directory in order to run (they are excluded by default when you run `$ mix test`). A few examples of running tests:
+Tests are organized with tags. Integration tests that hit real websites over the internet are tagged with `:requires_internet_connection`. Proxy tests are tagged with `:proxy` (excluded by default) and require that you start local proxy instance through Docker Compose (or Podman Compose) from the Mint root directory in order to run.
+
+If you encounter `{:error, %Mint.TransportError{reason: :nxdomain}}` error during the integration test, this suggests your DNS-based adblocker (self-hosted or VPN) might be blocking social media sites used in the integration test cases.
+
+Here are a few examples of running tests:
+
+Run all default tests which including `:requires_internet_connection` except `:proxy`:
 
-  * `$ mix test` to run the test suite without caring about Docker and `docker-compose up`.
+```sh
+mix test
+```
+
+Local tests, if you don't have an Internet connection available:
 
-  * `$ mix test --exclude integration` to only run local tests (for example, you don't have an internet connection available).
+```sh
+mix test --exclude requires_internet_connection
+```
 
-  * `$ mix test --include proxy` to run all tests, including proxy tests.
+Run all tests:
+
+```sh
+DOCKER_USER="$UID:$GID" docker-compose up --detach # or podman-compose up --detach
+mix test --include proxy
+```
 
 ## License
 
@@ -122,7 +143,7 @@ Copyright 2018 Eric Meadows-Jönsson and Andrea Leopardi
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
 
-      http://www.apache.org/licenses/LICENSE-2.0
+      https://www.apache.org/licenses/LICENSE-2.0
 
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,