Where is xUnit API reference / in detail documentation? (it is question, not Issue)

[ramin-rp]

Hello,
I like xUnit, but i can't find good documentation for it.
Where is API reference or detailed documentation for your library?

[alexander-dorfman]

Unfortunately, it looks like there is no official API nor official documentation apart from what you can find on main page.
I am forced to use samples in the repo + google.

[metasequoia]

+1

[bradwilson]

There is a documentation site: https://xunit.github.io/

However, there is no API documentation there. We ship the XML documentation in the ZIP file for Intellisense, but thus far have not worked on a system to automatically generate HTML from that XML.

[Neutrino-Sunset]

Not even a quickstart describing the concurrency, or setup/teardown semantics!

Worst. documentation. ever.

[bradwilson]

@Neutrino-Sunset Thank you for the constructive feedback.

FYI, both topics are already documented:
https://xunit.github.io/docs/shared-context.html
https://xunit.github.io/docs/running-tests-in-parallel.html

If you have any improvements to offer, we accept pull requests.

[cchamberlain]

Appreciate this project pushes good code styles over stale documentation. That being said, it would lower the bar to entry to have "the basics" documented in the documentation area of https://xunit.github.io.

If I get some time soon, will send a PR.

[borgdylan]

@bradwilson I'd recommend using monodoc to turn the xml doc file into something browsable.

[borgdylan]

For whoever has mono and therefore the mdoc command installed use the following (example for the asserts library, ran inside the lib/netstandard1.1 directory of the nuget package)

mdoc update -i *.xml -o docs xunit.assert.dll
mdoc export-html -o docs-html docs

Open the index.html file inside the docs-html folder using your preferred browser.

[bradwilson]

Closed for age.

[mishal153]

their tests may help understand/find the needed info. accuracy guaranteed

[maxalmonte14]

I think closing the issue is not the right solution but working on the problem. The xUnit documentation is really poor, and taking into account that this is the most used .NET testing framework it shouldn't be that way!

If we look at PHPUnit documentation for example, we find a lot of useful information, even a detailed list of every assertion available!

[bradwilson]

@maxalmonte14 In addition to being closed for age, it should also have been closed as being non-actionable. Issues need to be opened for specific, discrete bugs or tasks. "Please make X better" is too open ended to be usable.

As mentioned above, we welcome specific issues as well as PRs to improve the documentation (the docs site is on Github as well).

[canterberry]

Not to sound too snarky here, but I think what we're all asking for is documentation that reveals the answer to the following fundamental question:

❓ When I add the line using Xunit; to my code, what becomes available to me?

Such a document goes by many names: API Reference, Class Reference, or most libraries just call it "the docs", or the proverbial object of many an "RTFM" response.

Examples:

• .NET Core
• Mono

I'm trying to learn about Xunit and to understand what Assert looks like. Rather than trial-and-error and inspecting oodles of "sample code" that exercise various portions of what it might do, trying to use it as if it were MSTest's Assert class, I'd much rather just look at a document that illustrates "Here's what Assert does".

In the meantime, for others who find themselves here as the top Google search result for "Xunit API Reference", your best bet is to read through the Xunit source code itself. For convenience, here's what I think may be the implementation for Assert.

Edit: Actually, it looks like Assert is partially implemented across many different files in that repo, so you're on your own trying to locate a cohesive answer to "What, exactly, does Assert do?"

[bradwilson]

The API documentation is contained in the XML doc comments (which ship with the library). They are surfaced via Intellisense.

Since this is not a convenient form for browsing, there is an open issue to get the API documentation added to the web site: #1902

[tohagan]

Very disappointed to discover XUnit assertion docs are non-existent. All it takes is a brief one line per method to improve the situation. Tempts me to port my old NUnit wrapper over to XUnit to fix this. See how easy it is ...

• https://github.com/tohagan/ShouldBe#assertion-methods

[bartelink]

Sounds like it should be very easy for you to get over your disappointment by contributing that which you seek. I'm not sure how wrapping solves any problems.

[tohagan]

https://fluentassertions.com/ solves my problem. This solves the problem by wrapping the xUnit assertion API with BDD assertions that are fully documented and much nicer to use.

[18549]

https://fluentassertions.com/ solves my problem. This solves the problem by wrapping the xUnit assertion API with BDD assertions that are fully documented and much nicer to use.

Any API promoting 10 deep dotted method chaining and classes with properties called 'And' needs burning. What kind of OOP is that supposed to be?

If a result is expected to meet multiple expectations, the most readable expression of that is to have multiple statements. Jamming a dozen expressions into a single statement glued together with 'And' properties is horrible and unnecessary.

[bartelink]

As long as this nonsense doesn't make it into the core library and turn it from something with xmldoc into something needing a Friendly Manual or a 20 page README.me, it's all good ;)

Some day, it'll all collapse to something like this.

[bradwilson]

turn it from something with xmldoc into something needing a Friendly Manual or a 20 page README.me

We accept PRs for https://github.com/xunit/xunit.github.io

[krischik]

been closed as being non-actionable.

It's absolutely actionable: write better documentation.

The API documentation is contained in the XML doc comments

Which is useless without samples and explanation. Have a look at the Android documentation. That too is just JavaDoc documentation inside the code.

But it has examples, pictures, explanations. The Android documentation is useful.

[bartelink]

The Android documentation has the backing of a large number of full time devs and tech writers. xUnit has a good community, but nobody has a day job that's remotely connected to being responsible for write better documentation which they should be held accountable for.

and 🔥 I bet they have a 1% less entitled user community that will 2% more frequently bring the change they seek

To be clear: I'd also love to to have clear and complete documentation. But I won't be registering my strong dissatisfaction that it's not there until I demonstrate with pull requests and actual real contributions that I'm not just someone that wishes to register a complaint about the current state of the world.

[bradwilson]

@krischick I will refer you to the post immediately above yours: we accept PRs.

[Ruud-cb]

Was pretty excited about xUnit to try since this stackoverflow answer gave some good points, yet now discovering that xUnit doesn't even tell you how to do simple things is just... sad for more then 3 years already!

By now again looking at the documentation provided by NUnit, I'm immediately sold for their rich documentation.

[bartelink]

@Ruud-cb you can be the change you wish to see and be a part of making these things happen. While the feedback is not entirely useless, it adds up to kicking sand in faces and running off in the end from where I'm sitting.

Ultimately the maintainers + (generally very limited) community around a project have hard choices to make in terms of how to balance the use of their time on open source projects (remember, this stuff does not pay bills - its a labour of love and a gift).

As a 11 year+ user of xUnit, I deeply appreciate Brad's (and Jim, but really Brad :D) demonstrated commitment to making the hard choices of how to best invest their finite time, and the courage to say no to doing anything half-assed (i.e. saying no to adding some features, not straying into providing guidance on subjective matters around testing).

[mikek65]

I went to the GitHub site referenced above and it says the repo has been archived and is read-only. Does that mean PR's are not still accepted? I'm also needing documentation but am willing to contribute as time allows, if I can.

[patrickbucher]

No official API doc? Seriously? I'm trying to get into TDD with C#, which is one of the most frustrating endeavors I've ever tried.

[tohagan]

No official API doc? Seriously? I'm trying to get into TDD with C#, which is one of the most frustrating endeavors I've ever tried.

Checkout https://fluentassertions.com/ that wrappers xUnit. Nice docs.

[NilsFantastic]

No official API doc? Seriously? I'm trying to get into TDD with C#, which is one of the most frustrating endeavors I've ever tried.

I'm just going to answer this for future googlers:

There is no online documentation but there are documentation comments in the source code of xUnit itself.

You can see it by either:

1. Looking in the auto-complete for each specific function in visual studio
2. Decompiling the assert class and looking directly at the comments
3. Using a doc generator as discussed in this stack over flow thread

This may be obvious to some people but It needs to be pointed out in this thread.

[0bviouSquirre1]

As a brand-new programmer and user to xUnit, I don't have the experience or knowledge necessary to contribute anything yet, in large part because I cannot find any kind of documentation that could help get me to a place where I could make a contribution.

Having to install Yet Another Thing I Don't Understand (fluent assertions) just to make the Thing I Barely Understand somewhat usable is an incredibly daunting prospect for the newbie.

I just want to know why Assert.IsType(player) doesn't return true when I've literally just instantiated a Player object. Is this a Moq problem? I don't know, it's Yet Another Thing I Barely Understand that I've installed in the hopes that this stuff will Just Work one day.

If you want more contributions, it needs to be possible for new people to get spun up enough to contribute anything.

[bartelink]

re @NilsFantastic ☝️☝️

You can see it by either:

I would add

4. clone the repo and load the solution - there is no need to go decompiling things or using doc generators - use an IDE to navigate.

@0bviouSquirre1

I just want to know why Assert.IsType(player) doesn't return true when I've literally just instantiated a Player object. Is this a Moq problem? I don't know, it's Yet Another Thing I Barely Understand that I've installed in the hopes that this stuff will Just Work one day.

Taking a stab:

Assert.IsType<T> checks whether the type can be cast to the specified type. It's intended for use when checking an unknown object. It happens to return the dowcasted value for you to do further assertions on as desired.

If it cannot be downcast, it will have thrown already. It's possible that you are testing the Mock<T> holder/builder rather than the actual Mock Object - i.e. maybe you should be doing Assert.IsType<X>(mockX.Object) ?

edited to add: See Brad's post below - I confused Assert.IsType with Assert.IsAssignableFrom, though the thrust of how stuff is organised and works is consistent.

While some people watch this repo, the bottom line is that the Issues are for confirmed problems that are going to be solved in some clear way. Figuring out how to use it etc is best done either in the Discussions, or on Stackoverflow.com - there are way more people there. In both cases, it would be helpful to show what you are doing so people can get you unstuck quickly without having to guess what you are doing and what you've tried. (I only saw this because I was involved earlier in the thread)

And you absolutely don't need Fluent Assertions. The built in ones are not fluent. You can argue that some things are missing, but in general that's by design - the intentional lack of corner case features in xUnit.net is absolutely a feature.

(Fluent assertions and the like obviously have plenty followers, and plenty positives; just flagging the fact that many people intentionally use the built in Xunit ones despite being aware of and having tried other assertion libraries)

If you feel the desire to discuss and/or anyone else feels the desire to rant, please don't do it on this thread - create a Discussion or post on SO please

[0bviouSquirre1]

Wow, thank you! That was incredibly clear and helpful.

I only posted here to show support for the idea that this documentation is sorely needed, with my minor issue as an example. I wasn't expecting to receive actual help. I genuinely appreciate it.

[bartelink]

Not a problem - there's a heck of a lot of people that appreciate and use xUnit, and they do like to help where they can. Plenty people like me monitor thexunit tag on SO and answer questions like these as and when they arise (and lots of people are just randomly on SO and xUnit is pretty pervasive too). (Truth be told, another reason I monitor the tag is simply to gain awareness of new techniques etc - answering questions only happens if I have time. But that's OK - there are lots of other people on SO so you're not reliant on a single digit number of watchers of this repo understanding and/or guessing what your problem is having the time and inclination to reply)

.NET OSS being the way it is, sadly quality beginner to intermediate level docs don't just happen to the degree that they do in some other ecosystems. (NUnit and MSTest definitely have better docs, but they've also had more people working on them over time. Doesn't make me recommend them instead though!)

[bradwilson]

I just want to know why Assert.IsType(player) doesn't return true when I've literally just instantiated a Player object. Is this a Moq problem?

The answer is both "yes" and "no". 😁

The Intellisense for Assert.IsType says this:

So this assertion is checking for exact type, not compatible type; the latter is handled by Assert.IsAssignableFrom:

So why is this a Moq "problem"? Off the top of my head, there a couple ways it could go sideways:

1. You might have a Mock<Player> (which is not a Player)

If this is the case, as @bartelink notes above, calling .Object on the Mock<Player> will give you the instance of the mocked Player object. However, this puts you into the second situation:

2. The implementation of how mocking generally works is that it creates something that derives from Player so that it can override the virtual methods.

Assert.IsType is wrong, because you don't have an object of exactly the Player type, you have one that's derived from Player, so Assert.IsAssignableFrom is the right choice.

I cannot find any kind of documentation that could help get me to a place where I could make a contribution

There is a project site at https://xunit.net/ with some documentation, but it currently does not contain the documentation that you see with Intellisense (that's only available in a compatible editor like Visual Studio or VS Code). There is an open issue for this: #1902

[davidcian]

Leaving my 2 cents here: yes, I can read the source code, and I am sometimes forced to do so. It's not convenient though, and I like to avoid doing this when I can. Adding documentation is what I would call very low-hanging fruit: a little would go a very long way.

Here's the main reason: sure, if I want to know how something works, I'll go read the source code. Question is, how do I figure out what is available and how to do things? Read through the entire source code? That is an utterly undefendable position.

Who should add the doc and whether doc should be added are also two very different issues: the dev team's position is rather confusing with respect to these two issues.

[bradwilson]

@davidcian As ever, we would gladly accept PRs to address this.