support --black as arg for testing (#25271)

fixes #24966

Author: eleanorjboyd

.github/instructions/pytest-json-test-builder.instructions.md

@@ -0,0 +1,126 @@
+---
+applyTo: 'python_files/tests/pytestadapter/test_discovery.py'
+description: 'A guide for adding new tests for pytest discovery and JSON formatting in the test_pytest_collect suite.'
+---
+
+# How to Add New Pytest Discovery Tests
+
+This guide explains how to add new tests for pytest discovery and JSON formatting in the `test_pytest_collect` suite. Follow these steps to ensure your tests are consistent and correct.
+
+---
+
+## 1. Add Your Test File
+
+-   Place your new test file/files in the appropriate subfolder under:
+    ```
+    python_files/tests/pytestadapter/.data/
+    ```
+-   Organize folders and files to match the structure you want to test. For example, to test nested folders, create the corresponding directory structure.
+-   In your test file, mark each test function with a comment:
+    ```python
+    def test_function():  # test_marker--test_function
+        ...
+    ```
+
+**Root Node Matching:**
+
+-   The root node in your expected output must match the folder or file you pass to pytest discovery. For example, if you run discovery on a subfolder, the root `"name"`, `"path"`, and `"id_"` in your expected output should be that subfolder, not the parent `.data` folder.
+-   Only use `.data` as the root if you are running discovery on the entire `.data` folder.
+
+**Example:**
+If you run:
+
+```python
+helpers.runner([os.fspath(TEST_DATA_PATH / "myfolder"), "--collect-only"])
+```
+
+then your expected output root should be:
+
+```python
+{
+    "name": "myfolder",
+    "path": os.fspath(TEST_DATA_PATH / "myfolder"),
+    "type_": "folder",
+    ...
+}
+```
+
+---
+
+## 2. Update `expected_discovery_test_output.py`
+
+-   Open `expected_discovery_test_output.py` in the same test suite.
+-   Add a new expected output dictionary for your test file, following the format of existing entries.
+-   Use the helper functions and path conventions:
+    -   Use `os.fspath()` for all paths.
+    -   Use `find_test_line_number("function_name", file_path)` for the `lineno` field.
+    -   Use `get_absolute_test_id("relative_path::function_name", file_path)` for `id_` and `runID`.
+    -   Always use current path concatenation (e.g., `TEST_DATA_PATH / "your_folder" / "your_file.py"`).
+    -   Create new constants as needed to keep the code clean and maintainable.
+
+**Important:**
+
+-   Do **not** read the entire `expected_discovery_test_output.py` file if you only need to add or reference a single constant. This file is very large; prefer searching for the relevant section or appending to the end.
+
+**Example:**
+If you run discovery on a subfolder:
+
+```python
+helpers.runner([os.fspath(TEST_DATA_PATH / "myfolder"), "--collect-only"])
+```
+
+then your expected output root should be:
+
+```python
+myfolder_path = TEST_DATA_PATH / "myfolder"
+my_expected_output = {
+    "name": "myfolder",
+    "path": os.fspath(myfolder_path),
+    "type_": "folder",
+    ...
+}
+```
+
+-   Add a comment above your dictionary describing the structure, as in the existing examples.
+
+---
+
+## 3. Add Your Test to `test_discovery.py`
+
+-   In `test_discovery.py`, add your new test as a parameterized case to the main `test_pytest_collect` function. Do **not** create a standalone test function for new discovery cases.
+-   Reference your new expected output constant from `expected_discovery_test_output.py`.
+
+**Example:**
+
+```python
+@pytest.mark.parametrize(
+    ("file", "expected_const"),
+    [
+        ("myfolder", my_expected_output),
+        # ... other cases ...
+    ],
+)
+def test_pytest_collect(file, expected_const):
+    ...
+```
+
+---
+
+## 4. Run and Verify
+
+-   Run the test suite to ensure your new test is discovered and passes.
+-   If the test fails, check your expected output dictionary for path or structure mismatches.
+
+---
+
+## 5. Tips
+
+-   Always use the helper functions for line numbers and IDs.
+-   Match the folder/file structure in `.data` to the expected JSON structure.
+-   Use comments to document the expected output structure for clarity.
+-   Ensure all `"path"` and `"id_"` fields in your expected output match exactly what pytest returns, including absolute paths and root node structure.
+
+---
+
+**Reference:**
+See `expected_discovery_test_output.py` for more examples and formatting. Use search or jump to the end of the file to avoid reading the entire file when possible.

build/test-requirements.txt

@@ -39,3 +39,4 @@ pytest-describe
 
 # for pytest-ruff related tests
 pytest-ruff
+pytest-black

python_files/tests/pytestadapter/.data/2496-black-formatter/app.py

@@ -0,0 +1,6 @@
+def add(a, b):
+    return a + b
+
+
+def subtract(a, b):
+    return a - b

python_files/tests/pytestadapter/.data/2496-black-formatter/test_app.py

@@ -0,0 +1,14 @@
+import pytest
+from app import add, subtract
+
+
+def test_add(): # test_marker--test_add
+    assert add(2, 3) == 5
+    assert add(-1, 1) == 0
+    assert add(0, 0) == 0
+
+
+def test_subtract(): # test_marker--test_subtract
+    assert subtract(5, 3) == 2
+    assert subtract(0, 0) == 0
+    assert subtract(-1, -1) == 0

python_files/tests/pytestadapter/expected_discovery_test_output.py

@@ -1719,3 +1719,110 @@
     ],
     "id_": TEST_DATA_PATH_STR,
 }
+
+# This is the expected output for the 2496-black-formatter folder when run with black plugin
+# └── .data
+#    └── 2496-black-formatter
+#       └── app.py
+#          └── black
+#       └── test_app.py
+#          └── black
+#          └── test_add
+#          └── test_subtract
+black_formatter_folder_path = TEST_DATA_PATH / "2496-black-formatter"
+black_app_path = black_formatter_folder_path / "app.py"
+black_test_app_path = black_formatter_folder_path / "test_app.py"
+black_formatter_expected_output = {
+    "name": ".data",
+    "path": TEST_DATA_PATH_STR,
+    "type_": "folder",
+    "children": [
+        {
+            "name": "2496-black-formatter",
+            "path": os.fspath(black_formatter_folder_path),
+            "type_": "folder",
+            "id_": os.fspath(black_formatter_folder_path),
+            "children": [
+                {
+                    "name": "app.py",
+                    "path": os.fspath(black_app_path),
+                    "type_": "file",
+                    "id_": os.fspath(black_app_path),
+                    "children": [
+                        {
+                            "name": "black",
+                            "path": os.fspath(black_app_path),
+                            "lineno": "0",
+                            "type_": "test",
+                            "id_": get_absolute_test_id(
+                                "2496-black-formatter/app.py::black",
+                                black_app_path,
+                            ),
+                            "runID": get_absolute_test_id(
+                                "2496-black-formatter/app.py::black",
+                                black_app_path,
+                            ),
+                        }
+                    ],
+                },
+                {
+                    "name": "test_app.py",
+                    "path": os.fspath(black_test_app_path),
+                    "type_": "file",
+                    "id_": os.fspath(black_test_app_path),
+                    "children": [
+                        {
+                            "name": "black",
+                            "path": os.fspath(black_test_app_path),
+                            "lineno": "0",
+                            "type_": "test",
+                            "id_": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::black",
+                                black_test_app_path,
+                            ),
+                            "runID": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::black",
+                                black_test_app_path,
+                            ),
+                        },
+                        {
+                            "name": "test_add",
+                            "path": os.fspath(black_test_app_path),
+                            "lineno": find_test_line_number(
+                                "test_add",
+                                black_test_app_path,
+                            ),
+                            "type_": "test",
+                            "id_": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::test_add",
+                                black_test_app_path,
+                            ),
+                            "runID": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::test_add",
+                                black_test_app_path,
+                            ),
+                        },
+                        {
+                            "name": "test_subtract",
+                            "path": os.fspath(black_test_app_path),
+                            "lineno": find_test_line_number(
+                                "test_subtract",
+                                black_test_app_path,
+                            ),
+                            "type_": "test",
+                            "id_": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::test_subtract",
+                                black_test_app_path,
+                            ),
+                            "runID": get_absolute_test_id(
+                                "2496-black-formatter/test_app.py::test_subtract",
+                                black_test_app_path,
+                            ),
+                        },
+                    ],
+                },
+            ],
+        }
+    ],
+    "id_": TEST_DATA_PATH_STR,
+}

python_files/tests/pytestadapter/test_discovery.py

@@ -337,15 +337,37 @@ def test_config_sub_folder():
             assert tests.get("name") == "config_sub_folder"
 
 
-def test_ruff_plugin():
-    """Here the session node will be a subfolder of the workspace root and the test are in another subfolder.
+@pytest.mark.parametrize(
+    ("file", "expected_const", "extra_arg"),
+    [
+        (
+            "folder_with_script",
+            expected_discovery_test_output.ruff_test_expected_output,
+            "--ruff",
+        ),
+        (
+            "2496-black-formatter",
+            expected_discovery_test_output.black_formatter_expected_output,
+            "--black",
+        ),
+    ],
+)
+def test_plugin_collect(file, expected_const, extra_arg):
+    """Test pytest discovery on a folder with a plugin argument (e.g., --ruff, --black).
 
-    This tests checks to see if test node path are under the session node and if so the
-    session node is correctly updated to the common path.
+    Uses variables from expected_discovery_test_output.py to store the expected
+    dictionary return. Only handles discovery and therefore already contains the arg
+    --collect-only. All test discovery will succeed, be in the correct cwd, and match
+    expected test output.
+
+    Keyword arguments:
+    file -- a string with the file or folder to run pytest discovery on.
+    expected_const -- the expected output from running pytest discovery on the file.
+    extra_arg -- the extra plugin argument to pass (e.g., --ruff, --black)
     """
-    file_path = helpers.TEST_DATA_PATH / "folder_with_script"
+    file_path = helpers.TEST_DATA_PATH / file
     actual = helpers.runner(
-        [os.fspath(file_path), "--collect-only", "--ruff"],
+        [os.fspath(file_path), "--collect-only", extra_arg],
     )
 
     assert actual
@@ -359,8 +381,8 @@ def test_ruff_plugin():
         assert actual_item.get("cwd") == os.fspath(helpers.TEST_DATA_PATH)
         assert is_same_tree(
             actual_item.get("tests"),
-            expected_discovery_test_output.ruff_test_expected_output,
+            expected_const,
             ["id_", "lineno", "name", "runID"],
         ), (
-            f"Tests tree does not match expected value. \n Expected: {json.dumps(expected_discovery_test_output.ruff_test_expected_output, indent=4)}. \n Actual: {json.dumps(actual_item.get('tests'), indent=4)}"
+            f"Tests tree does not match expected value. \n Expected: {json.dumps(expected_const, indent=4)}. \n Actual: {json.dumps(actual_item.get('tests'), indent=4)}"
         )

python_files/vscode_pytest/__init__.py

@@ -17,7 +17,6 @@
 if TYPE_CHECKING:
     from pluggy import Result
 
-
 USES_PYTEST_DESCRIBE = False
 
 with contextlib.suppress(ImportError):

src/client/testing/testController/common/utils.ts

@@ -209,7 +209,14 @@ export function populateTestTree(
 
                 let range: Range | undefined;
                 if (child.lineno) {
-                    range = new Range(new Position(Number(child.lineno) - 1, 0), new Position(Number(child.lineno), 0));
+                    if (Number(child.lineno) === 0) {
+                        range = new Range(new Position(0, 0), new Position(0, 0));
+                    } else {
+                        range = new Range(
+                            new Position(Number(child.lineno) - 1, 0),
+                            new Position(Number(child.lineno), 0),
+                        );
+                    }
                 }
                 testItem.canResolveChildren = false;
                 testItem.range = range;