Documentation improvements

[connorshea]

I'd like to help improve the documentation of the test adapter example if possible.

Some things that I'd like to see, or that could use improvement:

• An example of what the runTests() function might look like.
• An example of updating the tests 'live' as the test suite outputs to stdout.
• An example unit test for the extension.
• An explanation of what exactly cancel() should do. Should it just kill the process, or should it also fire a "Test Suite Finished" event?

I'd also appreciate better documentation for the Adapter API and how it works, I know we can just read the code comments but I missed a decent number of features when creating my adapter due to the lack of documentation, e.g. the existence of tooltips or an error_message attribute when loading the tests. Is there a good library for generating a documentation website from the existing TypeScript files, and would you be interested in doing that?

Also, the README for the example should definitely link to the API and utils repositories.

Thanks for the Test Explorer! It's been a bit difficult to build my adapter at times, but I've also been learning TypeScript as part of it and I'm pretty happy with my progress. :)

[hbenl]

@connorshea @Raagh @rtbenfield @Testy @numaru @matepek @drleq @dampsoft @vshaxe @kondratyev-nv @recca0120 @DEVSENSE @swellaby @prash-wghats

I have started writing more documentation for Test Adapter authors here.
It's still incomplete (I need to add some stuff about how to implement debug() and dispose(), for example), but I hope it already contains some useful information.
Any comments and contributions would be very welcome.

P.S. I know this would have been more useful for you if I had written it earlier, but better late than never :)

[connorshea]

In this section workspaceFolder is never defined, it's just assumed to be there.

EDIT: I'm an idiot and didn't realize that was an arrow function for some reason 🤦‍♂

[connorshea]

Also, I should note that with this line in the example adapter, I'm pretty sure this prevents supporting more than one workspace folder?:

vscode-example-test-adapter/src/main.ts

Line 8 in 8bd4783

const workspaceFolder = (vscode.workspace.workspaceFolders || [])[0];

I have this problem in my Ruby adapter extension and I was just trying to fix it when I noticed that that was there :) Having support for multiple workspaces out-of-the-box with the example adapter would be nice.

EDIT: Actually, this seems to just be the way the workspaceFolder for the log instance is determined, so this doesn't need to be changed (a comment explaining this would be appreciated, though).

[numaru]

Hello @hbenl, this is appreciated. Thanks 👍

[hbenl]

In this section workspaceFolder is never defined

Do you mean the expression workspaceFolder => new MyTestAdapter(workspaceFolder)? In that case, the left hand side of the arrow is the declaration of the workspaceFolder variable.

[...] this prevents supporting more than one workspace folder?
const workspaceFolder = (vscode.workspace.workspaceFolders || [])[0];

Well, it doesn't prevent supporting more than one workspace folder, but the logging configuration (and only that) is taken from the first workspace folder and any logging config in other workspace folders is ignored. I should really fix that.

EDIT: I'm an idiot and overlooked your edits 😆