User Story Validator With NLP

English

This work was developed as my final work at UFSC to receive the Bachelor of Information Systems degree.

Requirements

• python 3.10+
• pip 22.2+
• Microsoft Visual C++ (only Windows)

Description

This API is in charge to evaluate user stories written using Mike Cohn's template and Gherkin's template. Stories are evaluated with three syntactic quality criteria:

Well formed: A story is well formed when there is an actor and an action. Purpose is optional.

Atomic: A story is atomic when there is only one action being performed.

Minimal: A story is minimal when it is well-formed and has no extra information, i.e. notes and additional information.

Preparation of sentences

A user story is a short, semi-structured sentence capable of illustrating the requirements of a software from the user's perspective, that is, it can be used to identify the user's desire for the product. Mike Cohn suggested the following template for writing a user story:

"As a [user type], I want [some purpose] so [some reason]."

This application is capable of processing stories following the Cohn template and also the Gherkin template:

"Given [precondition], when [action to be performed] then [expected result]".

To be possible, it is necessary to adapt the stories through keywords so that it is possible to segment the phrase. Therefore, follow the templates suggested below:

"I as [user type], I would like [some purpose] so [some reason]."

"Given [precondition], when [action to be performed] then [expected result]".

How to run the application

With python and pip installed, install virtualenv:

pip install virtualenv

After installing virtualenv, access the project directory and create the virtual environment:

virtualenv venv

Activate the virtualenv:

source venv/bin/activate (Linux or macOS)
venv/Scripts/Activate (Windows)

Once activated, install the dependencies:

pip install -r requirements.txt

Finally, launch the application:

python app.py

Executing the evaluation

After starting the application, go to:

localhost:5000/analisador

The endpoint /historia uses user stories in the Cohn's template, while the /cenario uses the Gherkin's template. Use the JSON files available in the examples folder to test and use as an example to create your own user stories.

Português

Este trabalho foi desenvolvido como meu trabalho de conclusão de curso na UFSC para receber o título de Bacharel em Sistemas de Informação.

Requisitos

• python 3.10+
• pip 22.2+
• Microsoft Visual C++ (apenas no Windows)

Descrição

Esta API tem como o objetivo avaliar histórias de usuário escritas utilizando o template de Mike Cohn e o template de Gherkin. As histórias são avaliadas dentro de três critérios de qualidade sintáticos:

Bem formada: uma história é bem formada quando há um ator e uma ação. A finalidade é opcional.

Atômica: uma história é atômica quando há apenas uma ação sendo executada.

Mínima: uma história é mínima quando é bem formada e não tem informações extras, ou seja, notas e informações adicionais.

Preparação das frases

Uma história de usuário é frase curta e semi-estruturada capaz de ilustrar os requisitos de um software na perspectiva do usuário, ou seja, pode ser usada para identificar o desejo do usuário com relação ao produto. Mike Cohn sugeriu o seguinte template para escrever uma história de usuário:

"Como [tipo de usuário], quero [algum objetivo] para que [algum motivo]."

Esta aplicação é capaz de processar histórias seguindo o template de Cohn e também o template de Gherkin:

"Dado [pré-condição], quando [ação que será executada] então [resultado esperado]".

Mas para que isso seja possível, é necessário adequar as histórias através de palavras chave para que seja possível segmentar a frase. Sendo assim, segue os templates sugerido logo abaixo:

"Eu como [tipo de usuário], gostaria [algum objetivo] para que [algum motivo]."

"Dado [pré-condição], quando [ação que será executada] então [resultado esperado]".

Como rodar a aplicação

Com o python e o pip instalado, instale o virtualenv:

pip install virtualenv

Após instalado o virtualenv, acesse o diretório do projeto e crie o ambiente virtual:

virtualenv venv

Ative a virtualenv:

source venv/bin/activate (Linux ou macOS)
venv/Scripts/Activate (Windows)

Após ativado, instale as dependências:

pip install -r requirements.txt

Por fim, inicie a aplicação:

python app.py

Executando a avaliação

Após iniciado a aplicação acesse:

localhost:5000/analisador

O endpoint /historia utiliza histórias de usuário no template de Cohn, já o /cenario utiliza ao template de Gherkin. Utilize os arquivos JSON disponíveis na pasta de exemplos para testar e tomar como exemplo para criar suas próprias histórias de usuário.