Sinon: Melhore a documentação para falsificações

As falsificações definitivamente precisam de documentos melhores. Talvez algo a abordar no proposto (ainda indeciso, @mroderick?) Hackathon de outubro?

@ fatso83 Eu gostaria de tentar.

Eu estaria atualizando o arquivo https://github.com/sinonjs/sinon/blob/master/docs/release-source/release/fakes.md ?

Também é o escopo deste problema definir quais funções estão disponíveis em um objeto fictício, talvez vinculando à documentação do espião e stub?

@peterjgrainger Isso é ótimo! O escopo e essa abordagem parecem razoáveis ​​...

Olhando para o código, as falsificações parecem ter a mesma API de um Spy e nada de um Stub.

Proponha a atualização dos documentos para remover a referência aos stubs, pois é um pouco enganador e acrescente que a API de falsificações é o mesmo que um espião

Grite 😮 se isso não parecer correto.

@peterjgrainger Obrigado por investigar isso. Posso ver semelhanças em spy , e stub eg fakes.throws() é o mesmo que stub().throws()

@ mshaaban0 obrigado pela entrada. Vou dar uma olhada mais de perto

@ fatso83 @ mshaaban0 Acho que entendi mal o escopo.

Achei que esse tíquete cobrisse a documentação da função falsa, por exemplo

var fake = sinon.fake();

não diretamente no próprio falso, ou seja,

sinon.fake

Pelo que posso ver, sinon.fake() retorna spy Acho que esta parte da documentação precisa ser esclarecida, pois o relator está pedindo documentação sobre o objeto em vez das funções estáticas.

Cheguei a esta conclusão porque parece que o objeto falso tem a propriedade called como um espião (não consigo encontrar isso documentado em qualquer lugar, exceto na documentação de espiões)

@itmayziii parece estar se referindo a sinon.fake() vez de sinon.fake

Acho que entendo o que fazer agora. Altere a documentação atual para dizer quais funções estáticas são inspiradas por um espião e quais são inspiradas por um esboço e mude o texto merged para descrever melhor a combinação de métodos e tente descobrir como distinguir entre sinon.fake e sinon.fake()

Você não é o único a entender mal o escopo. Que bom que você esclareceu para nós 😄

Este problema foi marcado automaticamente como obsoleto porque não teve atividades recentes. Ele será fechado se nenhuma outra atividade ocorrer. Obrigado por suas contribuições.

Acho que entendo o que fazer agora. Altere a documentação atual para dizer quais funções estáticas são inspiradas por um espião e quais são inspiradas por um esboço e mude o texto mesclado para descrever melhor a mistura de métodos, além de tentar descobrir como distinguir entre sinon.fake e sinon.fake ( )

O que é necessário fazer nesta questão? Se alguém deixar mais claro, gostaria de dar uma contribuição.

Como há uma seção chamada Instance properties , acho que apenas os métodos de uma função falsa precisam ser explicados. Se não houver outros métodos em uma função falsa além dos métodos de espionagem, acho que não há razão para refatorar os documentos atuais.

Obrigado 😊

@srknzl TBH, não me lembro muito bem, mas estes são alguns pontos que precisam de melhorias:

• Certifique-se de que a lista de métodos de fábrica estáticos em sinon.fake está completa
• Converta e / ou adicione alguns exemplos de Runkit executáveis ​​(muito fácil, mas leva um pouco de tempo)
• Atualize o link nas propriedades da instância para apontar para a mesma seção em Spies.
• Declare que os adereços listados são apenas um dos muitos da documentação de espiões e que você pode consultá-los para obter a lista completa
• Esclareça o texto para que fique claro que 1. A API Fakes é uma alternativa à API Stubs and Spies que pode substituir totalmente todos esses usos. 2. Destina-se a ser mais simples de usar, manter e ter uma superfície de API muito menor e evita muitos bugs por ter instâncias Fake imutáveis ​​em quazi (o comportamento não pode ser alterado após a criação (ao contrário de Stubs), mas eles têm um estado interno que muda quando usado, como callCount e outras estatísticas) 3. Uma instância Fake tem a API de um Spy (_é a_ Fake a Spy, @mroderick?)

A API Fakes é uma alternativa à API Stubs and Spies que pode substituir totalmente todos esses usos

Embora isso seja verdade, acho que usar um espião em vez de uma chamada falsa + substituição é mais fácil. Há algo que possa ser feito em relação a isto?

const foo = {bar: () => {}};
const aSpy = sinon.spy(foo, 'bar');
foo.bar();

console.log(aSpy.called); // true

vs

const foo = {bar: () => {}};
const barFake = sinon.fake(foo.bar);
sinon.replace(foo, 'bar', barFake);
foo.bar();

console.log(barFake.called); // true

Se fosse tão fácil quanto espiões, falsificações seriam as únicas que usarei.

Editar:

Eu descobri que posso fazer isso:

const foo = {bar: () => {}};
sinon.replace(foo, 'bar', sinon.fake(foo.bar));
foo.bar();
console.log(foo.bar.called); // true

pode valer a pena documentar esse uso também.

@srknzl Não tenho certeza se a chamada de substituição retorna algo, mas pode retornar o falso. Isso tornaria as coisas um pouco mais suaves.

Apenas verificado:

f = sinon.fake();
val=sinon.replace(o, 'b', f)
assert.equal(f,val);

o que significa que você pode escrever isto:

const foo = {bar: () => {}};
const fake = sinon.replace(foo, 'bar', sinon.fake());
foo.bar();
console.log(fake.calledOnce); // true

sim, faz sentido. Além disso, replace () não indica seu valor de retorno na página da sandbox

Apenas deixe claro, quais versões devem ser alteradas? Todas as versões que tem fake, certo? Ou apenas a próxima versão?

Outro feedback sobre a documentação em geral:

Posso entender que os verdes são links, mas alguns não verdes também são links, como sinon.replace* , sinon.spy e sinon.stub . Seria melhor, de alguma forma, torná-los diferentes

A impressão inicial está em https://github.com/sinonjs/sinon/pull/2360 , trabalho em andamento.

Estou esperando seu feedback.