Unable to generate Test Documents

[jpeters-ml]

I've been trying to generate documentation for our unit and ui test of a project that has cocoapods. I have created a simple project that is demonstrating my error (pasted below). The link to the project is JazzyTest.

I am using a script to invoke jazzy and when running the script for the app clause everything works as intended and the docs are generated in the JazzyTest/docs folder. However when I attempt to do the same for the JazzyTestTests it fails, while the log says that the build has succeeded (also linked below).

Installed version:

$ jazzy -v
jazzy version: 0.15.1

The steps I am taking are as follows:

1. clone repo to new directory
2. cd JazzyTest
3. pod install
4. cd ..
5. ./generateDocs.sh app <- To verify it's all good
6. ./generateDocs.sh ui <- Problem occurs at this step

Thank you for your time!

xcodebuild target/scheme output:

$ xcodebuild -workspace JazzyTest.xcworkspace -list
Command line invocation:
    /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -workspace JazzyTest.xcworkspace -list

User defaults from command line:
    IDEPackageSupportUseBuiltinSCM = YES

Information about workspace "JazzyTest":
    Schemes:
        CoreBluetoothMock
        CoreBluetoothMock-PrivacyInfo
        JazzyTest
        MSAL
        MSAL-MSAL
        Pods-Apps-JazzyTest
        Pods-Apps-JazzyTest-JazzyTestTests
        Pods-Apps-JazzyTestUITests

Console error:

/Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/executable.rb:39:in `execute_command': /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/bin/sourcekitten ["doc", "--module-name", "JazzyTestTests", "--", "-workspace", "JazzyTest.xcworkspace", "-scheme", "JazzyTest", "-destination\\=platform\\=ios\\ simulator", "name\\=iPad\\ \\(9th\\ generation\\)"] (RuntimeError)

2024-08-01 11:49:38.890 xcodebuild[39479:3252048]  DVTPlugInQuery: Requested but did not find extension point with identifier 'Xcode.InterfaceBuilderBuildSupport.PlatformDefinition'. This is programmer error; code should only request extension points that are defined by itself or its dependencies.

Running xcodebuild

Checking xcodebuild -showBuildSettings

Running xcodebuild

Could not parse compiler arguments from `xcodebuild` output.

Please confirm that `xcodebuild` is building a Swift module.

Saved `xcodebuild` log file: /var/folders/0t/m6b2x0tj5rsfxvr3_3fxvb1m0000gn/T/xcodebuild-F8463AF5-18A0-40E6-844C-148A05D4177E.log

Error: Failed to generate documentation

    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/sourcekitten.rb:229:in `run_sourcekitten'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:83:in `block (2 levels) in build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:81:in `chdir'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:81:in `block in build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:71:in `map'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/doc_builder.rb:71:in `build'
    from /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/bin/jazzy:16:in `<top (required)>'
    from /Users/user/.rbenv/versions/3.3.1/bin/jazzy:25:in `load'
    from /Users/user/.rbenv/versions/3.3.1/bin/jazzy:25:in `<main>'

Here's a link to the log file

Edited to add additional information.

[johnfairh]

The log file does not contain the string 'JazzyTestTests' at all - the only Swift build commands are for modules called JazzyTest and CoreBluetoothMock.

You need to give Jazzy the xcodebuild params that will make it build the module you want to document. I don't know enough about Xcode schemes & Cocoapods to suggest exactly what to do: either add that module to the scheme or use a different scheme that does include the module.

Jazzy (sourcekitten) is looking for a command in the log matching (approximately) swiftc -module-name <Your Module Name> so you can check this for yourself from a log or just running the xcodebuild command.

[jpeters-ml]

I've tried to create a scheme for the test targets specifically, and that only built the documentation for the app.

What I have noticed is that the xcode project for the app ,JazzyTest.xcodeproj in this case, does include a target for JazzyTestUITests. However, when using a workspace that target is not listed, nor am I able to specify that to xcodebuild.

Output of xcodebuild -list on the xcodeproj file:

$ xcodebuild -list
Command line invocation:
    /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -list

User defaults from command line:
    IDEPackageSupportUseBuiltinSCM = YES

Information about project "JazzyTest":
    Targets:
        JazzyTest
        JazzyTestTests
        JazzyTestUITests

    Build Configurations:
        Debug
        Release

    If no build configuration is specified and -scheme is not passed then "Release" is used.

    Schemes:
        JazzyTest

Output when -target is included in the xcodebuild parameters:

$ ./generateDocs.sh unit
2024-08-07 11:17:33.398 xcodebuild[93580:4705271] Writing error result bundle to /var/folders/0t/m6b2x0tj5rsfxvr3_3fxvb1m0000gn/T/ResultBundle_2024-07-08_11-17-0033.xcresult
xcodebuild: error: You cannot specify targets with a workspace.
Running xcodebuild
Could not successfully run `xcodebuild`.
Please check the build arguments.
Saved `xcodebuild` log file: /var/folders/0t/m6b2x0tj5rsfxvr3_3fxvb1m0000gn/T/xcodebuild-5401AE7B-8FDC-47FD-968D-68729474AB5A.log
Error: Failed to generate documentation
/Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/lib/jazzy/executable.rb:39:in `execute_command': /Users/user/.rbenv/versions/3.3.1/lib/ruby/gems/3.3.0/gems/jazzy-0.15.1/bin/sourcekitten ["doc", "--", "-workspace", "JazzyTest.xcworkspace", "-scheme", "JazzyTest", "-target", "JazzyTestTests", "-destination\\=platform\\=ios\\ simulator", "name\\=iPad\\ \\(9th\\ generation\\)"] (RuntimeError)

[jpeters-ml]

Since my last comment I have resolved my issue.

I have found that issue #504 has the answer to this question. In summary, you need to add either test or build-for-testing to build-tool-arguments in order for Xcode to generate the correct modules for jazzy to generate the documentation for tests.

Note that if you were to use test, this would cause the build to execute the tests as well as generate the necessary information for jazzy to generate the docs. You can specify that you want Xcode to skip the tests, however, using build-for-testing skips that part entirely.

As an enhancement of the documentation, it would be helpful if this information was included so that others experiencing this issue may easily find the solution.