DEV Community: Lucas Pacheco

Tips to debug authentication error with Kerberos on Windows Server

Lucas Pacheco — Tue, 11 Jun 2024 00:39:50 +0000

Authentication errors with Kerberos and Windows Server are not unusual. To be able to find these errors, there are a lot of internet pages about Kerberos and Windows Server. Therefore, below are some summarized steps that may help you identify any problems and possibly help you resolve them.

Steps

1 - Check that the application on the Windows Server has all authentication options disabled, except the Windows Authentication option, which must be enabled.

2 - In the Windows Authentication section, click on "Advanced Settings" and make sure that the Negotiate option is available and in the first position of the available list, if you wish to have authentication through NTLM, leave it second in the list.

3 - For performance matters, check the "Use kernel mode" option. This option uses the machine account by default to decrypt Kerberos tickets.

4 - If you use a custom account for your ApplicationPool, check the application configuration regarding WindowsAuthentication in the Configuration Editor. Access the path system.webServer/security/authentication/windowsAuthentication and make sure the UseAppPoolCredentials option is set to True.

5 - After ensuring that your WebServer and apps are well configured to receive Kerberos authentications and the error persists, you must check whether the settings of the account used are correct to authenticate with Kerberos.

6 - Check if the account's SPNs are correctly configured. To list the SPNs of an account you can run the following command in PowerShell from a machine inserted in the same AD domain you are using. It could be the server itself. Run the following command:

setspn -l domain\account_name

The command must return the SPNs configured on the account. Guarantee the account has the correct SPN with the name of the server being used for authentication. E.g. HTTP/myserver.com, SERV/myserv. Also verify that no repeated SPNs occur, as this can cause failures.

If you do not have SPNs configured, you can add SPNs to an AD account with the following command, if you have access to do so:

setspn -s HTTP/myserver.com

7 - If you use a MachineAccount to authenticate with Kerberos on your WebServer, check the SPNs configured in the MachineAccount on the server itself.

setspn -l server_name

If you do not have the correct SPNs, follow the steps to add an SPN in item 6.

I hope these steps helped you solve your problem as they helped me!

For other issues, please comment below, maybe we can help each other.

References

How to authenticate with Kerberos using .NET

Lucas Pacheco — Thu, 02 Mar 2023 18:13:21 +0000

Recently, I have had the not-so-easy task to authenticate some API calls using the Kerberos method authentication. After a while of reading some docs and digging stack overflow about this subject, I decided to post a summary of what I have discovered.

First of all, hope that your infrastructure is all set up within the same network and all SPNs are configured. Having this set up correctly will prevent you from some headaches when things go wrong, even if your code is correct.

If you are using Windows as your environment and your server is within the same network as the Kerberos Authentication Server you should be able to easily authenticate using the default credentials or passing the username and password using the Network Credentials class of .NET inside your HttpClientHandler when you configure your HttpClient. Make sure your server is added to the Active Directory that manages the authentication.

To authenticate using custom credentials you can use the following code inside your ConfigureServices method:

services.AddHttpClient<IConnector, Connector>().ConfigurePrimaryHttpMessageHandler(
      serviceProvider =>
            {
                var credentialsCache = new CredentialCache {
                    { new Uri("https://yoururl.com/endpoint"),
                      "Negotiate",
                      new NetworkCredential("USERACCOUNT", "PASSWORD", "DOMAIN")
                    }
                };

                var httpClientHandler = new HttpClientHandler {
                    UseProxy = false,
                    Credentials = credentialsCache,
                    UseDefaultCredentials = false,
                };
                return httpClientHandler;
            });

The above code should work fine both in Linux and Windows when doing a request to an endpoint that accepts the Kerberos authentication.

If you want to use the default credentials of your server, and you already have that set up in your environment you can use the following code inside your ConfigureServices method:

services.AddHttpClient<IConnector, Connector>().ConfigurePrimaryHttpMessageHandler(
   serviceProvider =>
            {
                var httpClientHandler = new HttpClientHandler {
                    UseProxy = false,
                    UseDefaultCredentials = true
                };
                return httpClientHandler;
            });

To get the above code working on Linux, you first need to configure the Kerberos tickets inside your server. To do that you should have the Kerberos configuration file, usually called krb5.conf file. Read more on Krb5.conf file. In addition to the configuration file, you need to have some libraries installed in your server: krb5-config, krb5-user, syslog-ng realmd, gss-ntlmssp. After you have all set up you should initialize your ticket using the kinit command, read more on kinit command.

Command example:

kinit -V keytabfile.keytab account@domain.com

You can check your tickets running this other command:

klist

After configuring it, you should be able to make a standard request using your HttpClient and .NET will add the Negotiate header with your Kerberos ticket. Hopefully, if the service you are calling is configured correctly, this should work.

All the above code uses the default built in HttpClient provided by .NET. Alternatively, you can try to authenticate with this great library called Kerberos.NET, read more on Kerberos.NET.

Also, you can try to execute a direct call inside your Linux server using curl to check if everything is right with the configuration of your Kerberos credentials and tickets. To run a curl command using the Kerberos tickets use this syntax:

curl -k --negotiate -u : -X --location --request <VERB> <URL>

Additionally, if you want to add the functionality of authorization and authentication with Kerberos or windows AD in a Linux environment you need to add a package in your project from Nuget, and add the following code to your Startup.cs :

package to install: Microsoft.AspNetCore.Authentication.Negotiate

public void ConfigureServices(IServiceCollection services) {
   services.AddAuthentication(NegotiateDefaults.AuthenticationScheme)
      .AddNegotiate();

   builder.Services.AddAuthorization(options =>
   {
       options.FallbackPolicy = options.DefaultPolicy;
   });
   // code continues
}

public void Configure(IApplicationBuilder app) {
   // code before
   app.UseAuthentication();
   app.UseAuthorization();
   // code continues
}

Hope that helps someone who is trying to authenticate with Kerberos using .NET!

Additional resources:

Originally posted on my blog: Lucas Pacheco Blog

Thoughts on Legacy Code

Lucas Pacheco — Wed, 11 Nov 2020 00:54:59 +0000

Behold, you get your first job as a developer, excited to work on new technologies, the ones you looked at on YouTube videos, on Twitter trending topics, on blog posts, and on many other websites. Then, in the first months of work, you receive the following dose of reality: maintenance of a legacy code. Whoever has never had to keep a legacy code, can be sure that one day it will!

Recently, I had to carry out some maintenance, and, believe me, adding new features to legacy systems. This prompted a question in me about the need to maintain legacy software and how to perform this maintenance. In addition, how we should develop our current codes to be maintained in the future.

Knowing your application

Before start running the code, try to understand:

What does this application accomplish?
How important is this application for the company?
What are the affected areas?
What is the purpose of your change?

I believe that making any changes to the code, before having answers to these questions, can be very dangerous for the business, because you simply do not know the possible impacts. Have you ever imagined a login service down because you didn't know there was a dependency? In addition, the time it takes you to develop something you don't fully understand is much longer than the time it took if you had studied the application before.

Application refactoring

It is very common during the analysis of the old code to see that thought: "What did you do here? Why did you do it like this? This is very wrong!". Before judging someone else's code, remember: you don't know the circumstances under which this application was developed and you yourself have certainly written very similar code that you are seeing. At this point, you have the opportunity to improve this part of the code, and when possible, this should certainly be done, as you will hardly be the last to touch this application. There are several refactoring techniques and several books, so if you want to go deeper into the subject, I recommend reading one of these specialized books on the subject.

Tests

At this point, you may think, "There are no tests on the project! This technology is very old!" Again, here is the opportunity for you to accomplish them. Nowadays, delivering any application without testing in production must be well thought out and justified. Of course, there may be some very old technologies that performing unit tests or other tests are more complicated or even impossible to perform. For these cases, it will be necessary to perform very good validation with functional tests. Whenever possible, look for the person in charge of the business area to validate these changes.

What should I do with my current applications?

First, reliable documentation can make future application maintenance much easier. It can be a board in JIRA, some User Stories, a document with functional requirements, any information you may have about what is being developed. But the most important thing is to make this information accessible. It is useless to document everything and keep it on your computer.

What environment settings are needed to run and develop your application? In one of my last projects, I had to perform maintenance on a system that only ran on Windows XP! Imagine how it was to get an XP machine in 2020 to develop. In addition, by knowing what resources are needed to start the application, a lot of time can be saved with execution errors.

Develop tests for your applications! They will certainly assist you during the current development and will assist you when you need to change it in the future. In addition to ensuring that your future changes will not break the code that has been in production for years.

When developing your current system, you can be sure that it will be bequeathed one day and you or someone will have to work on it in the future. So always think about it while working with your super-cool technology and writing code.

Today's hype is tomorrow's legacy!

Thanks for your time! Comment below any tips or doubts.

Web Scraping com .NET Core 3.1

Lucas Pacheco — Sun, 20 Sep 2020 23:00:00 +0000

Recentemente tive a necessidade de buscar algumas informações em sites que não possuíam uma API para recuperar os dados necessários. Então, decidi que iria utilizar algumas técnicas de web scraping para buscar as informações que precisava. Já havia construído alguns web scrapers com Python e PHP. Porém, decidi me desafiar e criar um com .NET Core 3.1 e C#. Para isso utilizei um pacote, disponível no gerenciador de pacotes Nuget, chamado AngleSharp. Este pacote pode ser encontrado aqui.

Para exemplificar aqui, vamos acessar o site pensador.com, e recuperar as citações que ficam disponíveis para visualização. Nosso objetivo então é recuperar as citações de um determinado autor ou tema e armazenarmos em nosso dispositivo.

Criação do projeto

Minha necessidade era construir esse banco de citações uma vez, sem a necessidade de ficar atualizando ou ter algum acesso remoto. Por este motivo decidi criar uma aplicação de linha de comando, para isso utilizei o próprio template disponibilizado pelo Visual Studio.

Após nomear o projeto e realizar sua criação, é necessário instalar o pacote AngleSharp como uma dependência do projeto. Para isso é necessário clicar com o botão direito do mouse em 'Dependencies', e selecionar a opção 'Manage NuGet Packages'. Você deve visualizar uma tela semelhante com a imagem abaixo:

Após clicar em instalar, nosso projeto está pronto para começarmos a realizar chamadas ao site.

Acessando o site

Poderíamos realizar as chamadas diretamente no método Main da aplicação, mas eu prefiro separar em classes diferentes algumas operações. Sendo assim, decidi criar uma pasta Services e criar uma classe ScrapperService.cs dentro. Essa será a classe responsável por acessar o site que desejamos e trazer nossos dados já modelados.

Nessa classe ScrapperService.cs vamos criar uma propriedade do tipo IBrowsingContext, que é uma interface do pacote AngleSharp, que será responsável por fazer a requisição às páginas web que desejamos acessar. A classe junto com o seu construtor ficará assim:

using AngleSharp;

namespace PensadorScrapper.Services
{
    class ScrapperService
    {
        private IBrowsingContext context { get; set; }

        public ScrapperService()
        {
            var config = Configuration.Default.WithDefaultLoader();
            context = BrowsingContext.New(config);
        }
    }
}

Nessa etapa já podemos escrever o método que irá realizar a leitura dos nossos dados de interesse, mas antes é importante abrirmos a página em nosso navegador para vermos como o DOM está organizado, para então organizarmos nossa estratégia de obtenção dos dados. Então, ao abrir a página inicial de algum tema de interesse podemos perceber a organização da página. Vou usar como exemplo citações com o tema de filosofia, a página pode ser visualizada abaixo:

Ao analisarmos dessa forma, conseguimos visualizar onde estão os elementos de interesse para nossa aplicação, que são: as citações e número total de citações. Necessitamos verificar o número total de citações para podermos calcular o número de páginas estimado que cada tema ou autor terá. Assim, conseguiremos extrair todas as citações de cada um.

Após a análise visual é necessário verificar a organização do documento HTML, como já sabemos nossos elementos de interesse, podemos clicar com o botão direito e inspecionar o elemento para irmos direto a ele no código. Verificando o elemento, podemos então clicar com o botão direito novamente e selecionar a opção de copiar seletor. Esse caminho é que utilizaremos para encontrar esse elemento em nossa aplicação com o AngleSharp, então guarde ele em algum lugar. Abaixo uma imagem exemplificando o que foi realizado.

Realizando a mesma etapa para o bloco das citações, temos dois seletores copiados:

Informação total de citações: #content > div.top > div.total
Todas citações da página: #content > div.phrases-list

Com esses dados em mãos podemos criar o método para buscar as citações na classe ScrapperService.cs, o método fica assim:

public async IAsyncEnumerable<Quote> GetQuotes(string assunto, int pagina)
        {
            var url = $"https://www.pensador.com/{assunto}/{pagina}";
            Console.WriteLine(url);
            var document = await context.OpenAsync(url);

            var quotesHtml = document.QuerySelectorAll("#content > div.phrases-list > .thought-card");

            foreach (var item in quotesHtml)
            {
                var autor = item.QuerySelector(".autor").Text();

                int id = int.Parse(item.GetAttribute("data-id"));

                var texto = item.QuerySelector(".frase").Text();

                if(item.QuerySelector(".insert-onlist") != null)
                {
                    continue;
                }

                yield return new Quote(id, autor.Trim(), texto.Trim());
            }
        }

Explicando o código acima:

Criamos um método assíncrono para buscar as citações, pois assim nossa aplicação não fica bloqueada enquanto realiza uma chamada HTTP para o servidor, e também pois o pacote do AngleSharp realiza essa leitura da página de forma assíncrona.
Como a lógica do método pode ser aplicada pra qualquer página ou tema, vamos passar esses dois parâmetros, tornando o método mais adaptável.
Montamos então a url de acesso concatenando os textos conforme o padrão que o site utiliza, que é algum desses dois:
- pensador.com.br*/tema/pagina*
- pensador.com.br*/autor/nome_autor/pagina*
Na linha com o código var document = await context.OpenAsync(url); é que realizamos a leitura do documento, com auxílio do pacote AngleSharp. Esse método nos retorna um objeto com a página mapeada onde é possível navegar através dos seus nós.
Como já havíamos anotado nossos seletores, podemos utilizar a função QuerySelectorAll para retornar os nós de interesse nesse documento. Para isso então passamos o nosso seletor de todas as citações como parâmetro, adicionado da classe que todas citações compartilham em comum, como pode ser observado abaixo:
- var quotesHtml = document.QuerySelectorAll("#content > div.phrases-list > .thought-card");
Após termos todos os nós das citações, podemos iterar sobre eles e buscar as informações internas de cada nó. Para isso utilizamos novamente o QuerySelector, porém agora passando os seletores de cada informação que queremos. Que nesse caso são: autor, frase e ID.
Como você pode perceber, esse método retorna um objeto Quote, e esse objeto deve ser criado por nós, para isso criei uma pasta Models, e então criei a classe modelo Quote.cs, que pode ser visualizada abaixo:

namespace PensadorScrapper.Models
{
    class Quote
    {
        public int Id { get; set; }
        public string Autor { get; set; }
        public string Texto { get; set; }

        public Quote(int id, string autor, string texto)
        {
            Id = id;
            Autor = autor;
            Texto = texto;
        }
    }
}

Dentro do laço então retornamos esse objeto Quote, com auxílio da palavra-chave yield, que fará com que as citações sejam retornadas assim que forem sendo recuperadas do site.

E como descobrimos quantas páginas existem?

Se nós chamarmos o método construído acima, nossa aplicação já vai retornar todas citações de cada página que passarmos como parâmetro. Mas e se quisermos executar nossa aplicação para buscarmos todas as páginas de um tema ou autor? Para isso que salvamos o seletor daquela parte da página que nos informava o número total de posts. Porém, se analisarmos outra página, de algum autor específico, por exemplo, veremos que algumas informações estão diferentes:

O site pensador, quando tem um artista famoso, muda o texto de total de citações, e também muda a estrutura do HTML, para isso então precisamos mapear esse seletor também. Logo, temos dois seletores distintos:

Artista Famoso: #content > div.autorTotal
Tema geral: #content > div.top > div.total

Precisamos construir então um método que retorna o número total de páginas que cada autor ou tema terá. Uma forma simples de fazer isso é dividir o número total de citações pela quantidade que é exibida na primeira página, para termos um valor aproximado. Poderíamos também sempre analisarmos os elementos de paginação no final da página, até não existir mais nenhum. Mas nessa implementação vou somente dividir o número total de citações pelas exibidas na tela. Mas sintam-se livres para alterar o código no github e implementar essa funcionalidade. Segue abaixo como o método ficou:

public async Task<int> GetTotalPages(string assunto)
        {

            var document = await context.OpenAsync($"https://www.pensador.com/{assunto}");

            var quotesHtml = document.QuerySelectorAll("#content > div.phrases-list > .thought-card");
            var textoTotal = "";

            int quantidadePorPagina;
            int total;

            if (document.QuerySelector("#content > div.top > div.total") != null)
            {
                textoTotal = document.QuerySelector("#content > div.top > div.total").Text();
                if (int.TryParse(Regex.Match(textoTotal, @"(?<=de )(.*)(?= pensamentos )").Value, out total))
                {
                    quantidadePorPagina = int.Parse(Regex.Match(textoTotal, @"(?<=-\n)(.\d)(?=)").Value);
                    total = int.Parse(Regex.Match(textoTotal, @"(?<=de )(.*)(?= pensamentos )").Value);
                }
                else
                {
                    total = int.Parse(Regex.Replace(textoTotal, @"[^\d]", ""));
                    quantidadePorPagina = quotesHtml.Count();
                }
            }
            else
            {
                total = int.Parse(document.QuerySelector("#content > div.autorTotal > strong:nth-child(2)").Text());
                var textoPagina = document.QuerySelector("#content > div.autorTotal > strong:nth-child(1)").Text();
                quantidadePorPagina = int.Parse(Regex.Match(textoPagina, @"(?<= )(.\d)(?=)").Value);
            }

            int paginas = total / quantidadePorPagina;

            Console.WriteLine("Total: " + total);
            Console.WriteLine("Paginas: " + paginas);

            return paginas;
        }

Esse método ficou um pouco extenso, e poderia ser otimizado, mas deixaremos para fazer isso em uma segunda versão. Para extrair as informações de total de citações e paginação utilizei Regex. Explicando de uma forma geral, o método acessa a primeira página do autor ou tema e verifica se está no padrão de totais de citação do tema ou autor, então utiliza as técnicas de QuerySelector para realizar a captura dos nós. Após isso, o valor total de citações é dividido pela quantidade de citações por página e armazenado em um inteiro para arredondarmos para baixo o total de páginas.

Acessando todas páginas de um tema específico ou autor

Agora que já possuímos um método para estimar o número total de páginas e outro método para buscar as citações dessa página, só necessitamos realizar um laço de repetição alterando a página até o total de página daquele autor ou tema. Para isso, podemos adicionar em nosso método Main da classe Program.cs . A classe fica assim:

using PensadorScrapper.Services;
using System;

namespace PensadorScrapper
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            ScrapperService scrapper = new ScrapperService();

            string assunto = "autor/william_shakespeare";

            Console.WriteLine($"\n\n\n\n\n\nAUTOR: william_shakespeare \n\n\n");

            var totalPaginas = await scrapper.GetTotalPages(assunto);
            Console.WriteLine("N de paginas: " + totalPaginas);

            for (var i = 1; i <= totalPaginas; i++)
            {
                await foreach (var quote in scrapper.GetQuotes(assunto, i))
                {
                    Console.WriteLine($"ID: {quote.Id} | Autor: {quote.Autor.Trim()} | Frase: {quote.Texto.Trim()}");
                }
                Console.WriteLine($"\n --------Página {i}--------- \n\n");
            }
        }
    }
}

Ao executarmos o código podemos ver como está funcionando nossa aplicação:

Ainda, se desejarmos buscar dados de mais de um autor ou tema poderíamos criar uma Lista de autores e iterar sobre ela chamando os nossos mesmos métodos, dessa maneira:

using PensadorScrapper.Models;
using PensadorScrapper.Services;
using System;
using System.Collections.Generic;

namespace PensadorScrapper
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            ScrapperService scrapper = new ScrapperService();

            List<string> autores = new List<string>{
                "jean_jacques_rousseau",
                "rene_descartes",
                "immanuel_kant",
                "john_locke",
                "blaise_pascal",
                "galileu_galilei",
                "michel_de_montaigne",
                "mary_wollstonecraft",
                "angela_davis",
                "hipatia_de_alexandria",
                "maquiavel",
                "adam_smith",
                "zygmunt_bauman",
                "baruch_espinosa",
                "friedrich_engels",
                "georg_wilhelm_friedrich_hegel",
                "soren_kierkegaard",
                "epicteto",
                "martin_heidegger",
                "michel_foucault",
                "martin_heidegger",
                "hannah_arendt"
            };

            foreach (var autor in autores)
            {
                string assunto = "autor/"+autor;

                Console.WriteLine($"\n\n\n\n\n\nAUTOR: {autor} \n\n\n");

                var totalPaginas = await scrapper.GetTotalPages(assunto);
                Console.WriteLine("N de paginas: " + totalPaginas);

                for (var i = 1; i <= totalPaginas; i++)
                {
                    await foreach (var quote in scrapper.GetQuotes(assunto, i))
                    {
                        Console.WriteLine($"ID: {quote.Id} | Autor: {quote.Autor.Trim()} | Frase: {quote.Texto.Trim()}");
                        QuotesRepository.SaveQuote(quote);
                    }
                    Console.WriteLine($"\n --------Página {i}--------- \n\n");
                }
            }


        }
    }
}

Conclusão

Pronto! Temos uma aplicação que realiza um Web Scraping no site pensador.com e retorna todas as citações disponíveis de um determinado autor ou tema. Claro que normalmente não é só isso que desejamos. Muitas vezes necessitamos armazenar essas informações. Por esse motivo eu já realizei também a integração dessa aplicação com um banco de dados, onde essas informações ficam armazenadas. Mas como o post já ficou extenso, vou tratar desta etapa em um outro post aqui. Utilizaremos SQLite para armazenar e recuperar esses dados. O código completo desse post, com a versão já utilizando o banco de dados pode ser encontrado no meu Github. Abaixo temos um GIF da aplicação funcionando:

Testes unitários em .NET Core utilizando xUnit

Lucas Pacheco — Mon, 27 Jul 2020 22:47:14 +0000

Sobre testes unitários

Testes unitários são aqueles onde é possível verificar a execução da menor parte testável do seu código. Geralmente essa parte é uma função ou um método. Utilizar a automação desses testes é crucial para garantirmos que o código realize aquilo que nós desenvolvedores esperamos.

Assim, devemos escrever nossos testes em um cenário limitado e específico. Testes mais complexos e que abrangem mais funcionalidades devem ser realizados através de testes de integração e serviços. Assim, os testes unitários devem certificar os códigos dentro do seu controle, abstraindo as questões de infraestrutura.

Acredito que realizando tarefas práticas é o melhor modo de compreender, então vamos ao código!

Criando nosso primeiro teste

Nesse exemplo irei demonstrar os testes unitários com .NET Core 3.1 e xUnit.
O primeiro passo é criarmos um projeto, pode ser uma aplicação de linha de comando para testarmos alguns métodos. Irei utilizar o Visual Studio 2019 para os exemplos. Ao criarmos nosso projeto, devemos ter uma classe Program, com esse conteúdo:

using System;

namespace UnitTestsNetCore
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

Para exemplificar a realização dos testes, vamos criar uma abstração de uma calculadora. Essa calculadora terá 4 métodos:

Somar(decimal Num1, decimal Num2)
Subtrair(decimal Num1, decimal Num2)
Multiplcar(decimal Num1, decimal Num2)
Dividir(decimal Num1, decimal Num2)

Para simplificar, cada método retornará o resultado apenas, logo nossa calculadora não terá um estado que armazenará os resultados. Nossa classe calculadora será apenas responsável por executar os métodos e retornar esse valor. No final temos uma classe com o conteúdo abaixo:

namespace UnitTestsNetCore
{
    class Calculadora
    {
        public decimal Somar(decimal Num1, decimal Num2) => Num1 + Num2;
        public decimal Subtrair(decimal Num1, decimal Num2) => Num1 - Num2;
        public decimal Multiplicar(decimal Num1, decimal Num2) => Num1 * Num2;
        public decimal Dividir(decimal Num1, decimal Num2) => Num1 / Num2;
    }
}

Agora que já temos nossa calculadora, podemos criar nossa classe de testes! Para isso utilizei o Visual Studio para criar um novo projeto do tipo XUnitTest na mesma solução. Então vamos adicionar o primeiro projeto que criamos como referência para este último. Para realizar isto basta adicionar este item no arquivo .csproj.

<ItemGroup>
    <ProjectReference Include="..\UnitTestsNetCore\UnitTestsNetCore.csproj" />
</ItemGroup>

Vamos criar então nossa classe de testes, e nela vamos instanciar a classe que desejamos em seu construtor (Calculadora). Após fazer isso já podemos escrever nosso primeiro teste. A classe de testes ficará assim:

using Xunit;
using UnitTestsNetCore;

namespace XUnitTestProject
{
    public class CalculadoraTest
    {
        private readonly Calculadora _sut;
        public CalculadoraTest()
        {
            _sut = new Calculadora();
        }

        [Fact]
        public void Somar_DeveRetornarValor_QuandoInformadoAmbosNumeros()
        {

            var resultado = _sut.Somar(1, 2);
            Assert.Equal(3, resultado);
        }
    }
}

Nesse momento, nós temos nossa classe Calculadora como uma propriedade da nossa classe de testes, e podemos utilizar ela em todos os testes que desejarmos. Para definirmos algum método como um método de testes precisamos adicionar o atributo [Fact], na linha acima do método. Desse modo o xUnit saberá que esse método é um teste e deve ser chamado. No conteúdo do método temos a execução da função Somar(). Na última linha, verificamos se a função ocorreu como esperado. O primeiro parâmetro é o valor esperado e o segundo o valor atual que temos de retorno. Se executarmos os testes, tudo deve ocorrer sem nenhuma falha. Como pode ser visto abaixo:

Antes de escrevermos mais testes, se olharmos para o nosso método veremos que ele está testando somente um cenário. Que é a soma de 1 e 3. Para testarmos diferentes cenários no mesmo método, podemos mudar o atributo [Fact] para [Theory]. Ao realizar isso, precisamos também passar quais os cenários que desejamos, para isso utilizaremos o atributo [InLineData(params)]. Cada [InLineData(params)] que colocarmos, o xUnit irá realizar um teste. Vamos alterar para Theory e alterar o nosso método para aceitar 3 parâmetros. Precisamos informar qual o valor esperado e os dois valores para soma. Então o código ficará assim:

[Theory]
[InlineData(3, 2, 1)]
[InlineData(1, 2, -1)]
[InlineData(20, 20, 0)]
public void Somar_DeveRetornarValor_QuandoInformadoAmbosNumeros(decimal esperado,
                                                                decimal Num1,
                                                                decimal Num2)
{
    var resultado = _sut.Somar(Num1, Num2);
    Assert.Equal(esperado, resultado);
}

Ao rodarmos os nossos testes, a função será executada 3 vezes com os parâmetros definidos nos [InLineData(params)]. O retorno no Visual Studio ficará assim:

A biblioteca xUnit possui diversas funcionalidades para testarmos os nossos códigos que vão além de verificar se o retorno é igual ou diferente. Podemos verificar logs, status de requisições, conteúdos, e inúmeras outras funcionalidades. Podemos configurar se os testes irão rodar em paralelo ou não, definirmos se a classe que está sendo testada será ou não compartilhada entre os testes, as possibilidades são enormes. Aqui está somente o básico de como testar uma função, recomendo fortemente a leitura dos materiais de referência que coloquei no final do post.

O próximo post então será mais rápido e irá explicar algumas outras possibilidades um pouco mais avançadas utilizando xUnit e Mocks.

O código do final do projeto, com os testes dos outros métodos, pode ser encontrado aqui: Github