javascript
/
three.js
mirror of https://github.com/tazdij/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257
							<!DOCTYPE html>
<html lang="fr">
	<head>
		<meta charset="utf-8">
		<base href="../../../" />
		<script src="page.js"></script>
		<link type="text/css" rel="stylesheet" href="page.css" />
	</head>
	<body>
		<h1>Tests avec NPM ([name])</h1>

		<p class="desc">
			Ici vous sera expliqué comment obtenir three.js dans un environnement [link:https://nodejs.org/en/ node.js] pour que
			vous puissez exécuter des tests automatisés. Les tests peuvent êtres lancés en lignes de commande, ou grâce à des
			outils de CI automatisés comme [link:https://travis-ci.org/ Travis].
		</p>

		<h2>La version courte</h2>

		<p>
			Si vous êtes à l'aise avec node et npm,
			<code>
				$ npm install three --save-dev
			</code>
			et ajoutez
		<code>
			const THREE = require('three');
		</code>
			à votre test.
		</p>

		<h2>Créer un projet testable de zéro</h2>
		<p>
			Si vous n'êtes pas familier avec ces outils, vous trouverez ici un guide rapide (pour linux, le processus d'installation
			sera légèrement différent de celui pour Windows, mais les commandes NPM sont identiques).
		</p>

		<h3>Setup basique</h3>
		<div>
			<ol>
				<li>
					Installez [link:https://www.npmjs.org/ npm] et nodejs. La méthode la plus rapide ressemble généralement à
					<code>
$ sudo apt-get install -y npm nodejs-legacy
# fix any problems with SSL in the default registry URL
$ npm config set registry http://registry.npmjs.org/
					</code>
				</li>

				<li>
					Créez un nouveau répertoire de projet
					<code>
						 $ mkdir test-example; cd test-example
					</code>
				</li>

				<li>
					Demandez à npm de créer un nouveau fichier de projet pour vous:
					<code>
					 $ npm init
					</code>
					 et acceptez tous les paramètres par défaut en appuyant sur Entrée à chaque prompt.
					 Cela créera package.json.
				</li><br />

				<li>
					Essayez la fonctionnalité de test avec
					<code>
$ npm test
					</code>
					Cela va échouer, comme prévu.
					Si vous jetez un coup d'oeil à votre package.json, la définition du test de script sera
					<code>
						"test": "echo \"Error: no test specified\" && exit 1"
					</code>
				</li>

			</ol>
		</div>

		<h2>Ajouter mocha</h2>
		<div>
			Nous allons utiliser [link:https://mochajs.org/ mocha].

			<ol>
				<li>
					Installez mocha avec
					<code>
$ npm install mocha --save-dev
					</code>
					Remarquez que node_modules/ est créé et que vos dépendances y apparaissent.
				  	Notez également que votre package.json a été mis à jour: la propriété devDependencies
					est ajoutée et mis à jour par l'utilisation de --save-dev.
				</li><br />

				<li>
					Modifiez votre package.json pour qu'il utilise mocha pour effectuer les tests. Lorsqu'un test est invoqué, nous voulons simplement lancer
					mocha et spécifier un verbose reporter. Par défaut cela lancera le contenu de test/
					(ne pas avoir de répertoire test/ peut causer une npm ERR!, créez le en utilisant mkdir test)
					<code>
						"test": "mocha --reporter list"
					</code>
				</li>

				<li>
					Relancez les tests avec
					<code>
						$ npm test
					</code>

					Cela doit maintenant réussir, signalant 0 passages (1ms)
				 	ou similaire.
				</li>

			</ol>
		</div>

		<h2>Ajouter three.js</h2>
		<div>
			<ol>
				<li>
					Ajoutons notre dépendance de three.js avec
					<code>
$ npm install three --save-dev
					</code>
					<ul>
						<li>
							Si vous avez besoin d'une version de three différente, utilisez
							<code>
								$ npm show three versions
							</code>
						  	pour voir
							ce qui est disponible. Pour indiquer à npm la bonne, utilisez
							<code>
 $ npm install [email protected] --save
							</code>
							(0.84.0 dans cet exemple). --save qui en fait une dépendance de ce projet, au lieu
							d'une dépendance dev. Voir la documentation [link:https://docs.npmjs.com/cli/v8/configuring-npm/package-json ici] pour plus d'informations.
						</li>
					</ul>
				</li>

				<li>
					Mocha cherche des tests dans test/, exécutons donc la commande
					<code>
					$ mkdir test
					</code>
				</li>

				<li>
					Finalement, nous avons besoin d'un test JS à lancer. Ajoutons un test simple qui va vérifier que
					l'objet three.js est disponible et fonctionnel. Créez test/verify-three.js contenant:
<code>
const THREE = require('three');
const assert = require('assert');

describe('The THREE object', function() {
  it('should have a defined BasicShadowMap constant', function() {
    assert.notEqual('undefined', THREE.BasicShadowMap);
  }),

  it('should be able to construct a Vector3 with default of x=0', function() {
    const vec3 = new THREE.Vector3();
    assert.equal(0, vec3.x);
  })
})
</code>
				</li>

				<li>
				Finalement testons à nouveau avec $ npm test. Cela doit lancer le test ci-dessous et réussir,
				affichant quelque chose du genre:
				<code>
The THREE object should have a defined BasicShadowMap constant: 0ms
The THREE object should be able to construct a Vector3 with default of x=0: 0ms
2 passing (8ms)
				</code>
				</li>
			</ol>
		</div>

		<h2>Ajoutez votre propre code</h2>
		<div>
			Vous devez faire trois choses:

			<ol>
				<li>
					Écrivez un test pour un comportement attendu de votre code, et placez-le sous test/.
					[link:https://github.com/air/encounter/blob/master/test/Physics-test.js Ici] vous trouverez un exemple issu d'un vrai projet.
				</li>

				<li>
					Exportez votre code de manière à ce que nodejs puisse le voir et l'utiliser quand la conjoncture le requiert.
					Voir [link:https://github.com/air/encounter/blob/master/js/Physics.js ici].
				</li>

				<li>
					Puis il faut require votre code dans le fichier de test, de la même manière que nous avons require('three') dans l'exemple au-dessus.
				</li>
			</ol>

			<p>
			Les items 2 et 3 varient selon la façon dont vous organisez votre code. Dans l'exemple de Physics.js
		  	montré plus-haut, la partie concernant l'export est à la toute fin. Nous assignons un objet à module.exports:
			</p>
			<code>
//=============================================================================
// make available in nodejs
//=============================================================================
if (typeof exports !== 'undefined')
{
  module.exports = Physics;
}
			</code>
		</div>

		<h2>Gérer les dépendances</h2>
		<div>
			<p>
				Si vous utlisez déjà quelque chose d'astucieux comme require.js ou browserify, sautez cette partie.
			</p>
			<p>
				Généralement un projet three.js s'exécute dans le navigateur. Le module de chargement est par conséquent réalisé par
				le navigateur qui exécute un ensemble de scripts. Vos fichiers individuels n'ont pas à gérer les
				dépendances. Dans un contexte nodejs, il n'y a pas d'index.html reliant tout
				ensemble, vous devez donc être explicites.
			</p>
			<p>
				Si vous exportez un module qui dépend d'autres fichiers, vous devrez dire à node de les charger.
				Voici une approche:
			</p>
			<ol>
				<li>
					Au début de votre module, vérifiez si vous êtes dans un environnement nodejs.
				</li>
				<li>
					Si c'est le cas, déclarez explicitement vos dépendances.
				</li>
				<li>
					Si ce n'est pas le cas, vous êtes probablement dans un navigateur vous n'avez donc rien d'autre à faire.
				</li>
			</ol>
			Code d'exemple issu de Physics.js:
			<code>
//=============================================================================
// setup for server-side testing
//=============================================================================
if (typeof require === 'function') // test for nodejs environment
{
  const THREE = require('three');
  const MY3 = require('./MY3.js');
}
			</code>
		</div>

	</body>
</html>